Google Pay payment handler

Overview

Google Pay payment handler for Universal Commerce Protocol (UCP) enables users and merchants to use Google Pay as a credential provider on Google AI surfaces like Gemini and AI Mode. Using Google Pay, users select their preferred payment method from Google Wallet during checkout. Google Pay then conveys this selection to the merchant as a secure payment instrument to complete the transaction.

You can use your existing payment system - Google Pay works with Payment Service Providers (PSPs) around the world.

Note: You can start using the Google Pay payment handler for UCP immediately — no existing website or app integration is required. However, Google recommends implementing the Google Pay API across all your digital storefronts to provide your customers with the same fast, secure checkout experience everywhere they shop.

Merchant integration for checkout

Payment processing options

• PAYMENT_GATEWAY integration is ideal for merchants that use a supported payment service provider gateway. With gateway integration, Google includes an encrypted payload in checkout completion that you convey to your PSP for processing.
• DIRECT integration is optional for PCI DSS Level 1 compliant merchants that can provide documentation. This integration requires you to decrypt payment credentials and process them directly with the card networks.

Declaring payment handler support

The Google Pay payment handler declaration indicates that your business accepts Google Pay, what payment methods and networks you support, and lets you request additional information to transact and fulfill orders.

Configuration

Google Pay payment handler is identified by the name com.google.pay inside the payment_handlers object.

The following table describes the properties of the payment handler configuration object:

Property	Type	Necessity	Description
id	string	Required	A unique identifier for this handler instance.
version	string	Required	The version of the Google Pay payment handler specification. This must be 2026-01-23.
spec	string	Required	The URL of the specification. This must be https://pay.google.com/gp/p/ucp/2026-01-23/.
schema	string	Required	The URL of the configuration schema JSON file. This must be https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json.
config	object	Required	Google Pay payment handler configuration options. For details, see the Google Pay payment handler configuration.

Example Google Pay payment handler declaration

{
  "payment_handlers": {
    "com.google.pay": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "version": "2026-01-23",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
        "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "KWMZPRLQFTYNXSDB",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": [ "PAN_ONLY" ],
                "allowed_card_networks": [
                  "AMEX",
                  "DISCOVER",
                  "JCB",
                  "MASTERCARD",
                  "VISA"
                ],
                "billing_address_required": true,
                "billing_address_parameters": {
                  "format": "FULL",
                  "phone_number_required": true
                }
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

Discoverability

You must provide a Google Pay payment handler declaration in your UCP well-known profile so that Google AI surfaces can determine whether to make Google Pay available to users during checkout.

Checkout session

You must also provide the payment handler declaration in Google UCP checkout responses to ensure that the correct payment options are available and that the system enforces the necessary requirements for each checkout session.

Processing payments

When checkout completes, Google sends a UCP Payment object (including a payment instrument) to the complete checkout endpoint defined in your UCP well-known profile.

Payment instrument

For details on the payment instrument structure, see Google Pay payment instrument.

Example Google Pay payment instrument

{
  "id": "pm_1234567890abc",
  "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
  "type": "card",
  "display": {
      "brand": "VISA",
      "description": "Visa •••• 4242",
      "last_digits": "4242"
  },
  "billing_address": {
    "street_address": "123 Main Street",
    "extended_address": "Suite 400",
    "address_locality": "Charleston",
    "address_region": "SC",
    "postal_code": "29401",
    "address_country": "US",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "credential": {
    "type": "PAYMENT_GATEWAY",
    "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
  }
}

Production access

To use production payment methods, you need to provide a merchant ID for a Google Pay & Wallet Console account with production access. For more information, see Prepare for production.