Google Pay payment handler specification

Handler Name: com.google.pay
Version: 2026-01-11

1. Introduction

The com.google.pay handler enables businesses to offer Google Pay as an accelerated checkout option through UCP-compatible platforms. The Google Pay API enables fast checkout by giving users access to payment methods stored in their Google Account.

This handler enables a headless integration model where businesses provide their Google Pay configuration (such as allowed card networks and gateway parameters), and platforms handle the client-side interaction with the Google Pay API to generate a secure payment token.

1.1 Key Benefits

Universal Configuration: Businesses configure Google Pay once using standard JSON, allowing any authorized platform to render the payment interface without custom frontend code.
Decoupled Frontend: Platforms handle the complexity of the Google Pay JavaScript API or SDK integration, while businesses consume the resulting token.
Secure Tokenization: Leverages Google's built-in tokenization to pass encrypted credentials directly to the business's Payment Service Provider (PSP).

2. Business Integration

2.1 Requirements

Before advertising Google Pay through UCP, businesses must:

Obtain Google Pay Merchant ID: Required for processing in the PRODUCTION environment (register in the Google Pay & Wallet Console).
Verify PSP Support: Ensure your Payment Service Provider (PSP) is in the list of supported processors and gateways for Google Pay tokenization.

2.2 Handler Configuration

Businesses advertise Google Pay support by including the handler in their payment handlers array. The configuration strictly follows the structure required to initialize the Google Pay API.

2.2.1 Configuration Schema

The configuration object defines the environment, business identity, and allowed payment methods.

Google Pay Payment Method

Based on Google Pay's PaymentMethod.

Tokenization Specification

Based on Google Pay's TokenizationSpecification.

2.2.2 Example Handler Declaration

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "01234567890123456789",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": ["PAN_ONLY"],
                "allowed_card_networks": ["VISA", "MASTERCARD"]
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

2.3 Entities

2.3.1 Instrument Schema

The Google Pay instrument (card_payment_instrument) extends the base Card Payment Instrument. It inherits standard display fields (like brand and last_digits) to ensure consistent receipt rendering, while refining the credential field to carry the specific Google Pay tokenization payload.

Platform Behavior: The platform is responsible for mapping from the Google Pay PaymentMethodData response into this structure before sending it to the business.

Name	Type	Required	Description
id	string	Yes	A unique identifier for this payment instrument, assigned by the platform.
handler_id	string	Yes	Identifier for the Google Pay handler.
type	string	Yes	Constant = `card`. Indicates this instrument behaves like a card (inherits card display fields).
brand	string	Yes	The card network (e.g., `visa`, `mastercard`). Mapped from Google Pay's `info.cardNetwork`.
last_digits	string	Yes	The last 4 digits of the card. Mapped from Google Pay's `info.cardDetails`.
rich_text_description	string	No	An optional rich text description of the card (e.g., "Visa ending in 1234, expires 12/2025").
rich_card_art	string (uri)	No	An optional URI to a rich image representing the card (e.g., issuer card art).
billing_address	Postal Address	No	The billing address associated with the card.
credential	Credential Payload	No	The secure tokenization data returned by Google Pay.

Credential Payload

This object serves as the credential for the instrument. It maps directly to Google Pay Tokenization Data.

Postal Address

This object serves as the address field. It maps directly to PostalAddress.

3. Platform Integration

3.1 Requirements

Before handling com.google.pay payments, platforms must:

Be capable of loading the Google Pay API for Web (or Android equivalent).
Adhere to the Google Pay Brand Guidelines when rendering the payment button.

3.2 Payment Protocol

Platforms MUST follow this flow to process the handler:

Step 1: Discover & Configure

The platform initializes the client to manage the API lifecycle.

Reference: PaymentsClient

Step 2: Check Readiness to Pay

The platform checks if the user has the ability to make a payment with the specified payment methods before displaying the button.

Reference: isReadyToPay

Step 3: Build Payment Request

The platform assembles the payment data request object, including the merchant configuration, payment methods, and transaction details (price and currency).

Reference: PaymentDataRequest

Step 4: Invoke User Interaction

The platform triggers the payment sheet display when the user interacts with the payment button.

Reference: loadPaymentData

Step 5: Complete Checkout

Upon successful user interaction, the Google Pay API returns a PaymentInstrument object under the payment_data key. The platform maps this response to the card_payment_instrument schema and submits the checkout completion request.

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "brand": "visa",
    "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\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

4. Business Processing

Upon receiving a Google Pay payment instrument, businesses MUST:

Validate Handler: Confirm handler_id corresponds to the Google Pay handler.
Extract Token: Retrieve the token string from payment_data.credential.token.
Process Payment: Pass the token string and the transaction details to the PSP's endpoint.
- Note: Most PSPs have a specific field for a "Google Pay Payload" or a "Network Token".
Return Response: Respond with the finalized checkout state (Success/Failure).

5. Security Considerations

5.1 Token Security

PAYMENT_GATEWAY: When using this tokenization type, the token is encrypted specifically for the tokenization party. The pass-through party cannot decrypt this token and should pass it through to the tokenization party as-is.
DIRECT: If using DIRECT tokenization, the business receives encrypted card data that they must decrypt. This significantly increases PCI DSS compliance scope and is generally not recommended unless the business is a Level 1 PCI Compliant Service Provider.

5.2 Environment Isolation

TEST Mode: In the TEST environment, Google Pay returns dummy tokens. These cannot be charged.
PRODUCTION Mode: Real cards are used. Businesses must ensure their PSP credentials in config.allowed_payment_methods match the environment.

Embedded checkout (optional)

Identity linking (optional)

Google Pay payment handler specification Stay organized with collections Save and categorize content based on your preferences.