# 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:

1.  **Obtain Google Pay Merchant ID:** Required for processing in the
    `PRODUCTION` environment (register in the
    [Google Pay & Wallet Console](https://pay.google.com/business/console)).
2.  **Verify PSP Support:** Ensure your Payment Service Provider (PSP) is in the
    [list of supported processors and gateways](https://developers.google.com/pay/api#participating-processors)
    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](https://developers.google.com/pay/api/web/reference/request-objects).

#### 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](https://developers.google.com/pay/api/web/reference/request-objects#PaymentMethod).

##### Tokenization Specification

Based on
[Google Pay's TokenizationSpecification](https://developers.google.com/pay/api/web/reference/request-objects#PaymentMethodTokenizationSpecification).

#### 2.2.2 Example Handler Declaration

```json
{
  "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`](https://developers.google.com/pay/api/web/reference/response-objects#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](#postal-address)         | No       | The billing address associated with the card.
credential            | [Credential Payload](#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](https://developers.google.com/pay/api/web/reference/response-objects#PaymentMethodTokenizationData).

#### Postal Address

This object serves as the `address` field. It maps directly to
[PostalAddress](https://ucp.dev/schemas/shopping/types/postal_address.json).

## 3. Platform Integration

### 3.1 Requirements

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

1.  Be capable of loading the **Google Pay API for Web** (or Android
    equivalent).
2.  Adhere to the
    [Google Pay Brand Guidelines](https://developers.google.com/pay/api/web/guides/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](https://developers.google.com/pay/api/web/reference/client#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](https://developers.google.com/pay/api/web/reference/client#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](https://developers.google.com/pay/api/web/reference/request-objects#PaymentDataRequest)

#### Step 4: Invoke User Interaction

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

*   **Reference:**
    [loadPaymentData](https://developers.google.com/pay/api/web/reference/client#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.

```json
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:

1.  **Validate Handler:** Confirm `handler_id` corresponds to the Google Pay
    handler.
2.  **Extract Token:** Retrieve the token string from
    `payment_data.credential.token`.
3.  **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".*
4.  **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.