# Google Pay payment handler specification
* **Handler Name:** `com.google.pay`
* **Version:** `2026-01-23`
## 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 support 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 registry. 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
{
"version": "2026-01-23",
"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/schema.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"],
"billing_address_required": true,
"billing_address_parameters": {
"format": "FULL"
}
},
"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**.
**Display Information:**
Visual properties such as `brand`, `last_digits`, and `card_art` are
encapsulated within the inherited `display` object.
**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.
display | object | **Yes** | Inherited display properties (brand, last digits, 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": {
"instruments": [
{
"id": "pm_1234567890abc",
"handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
"type": "card",
"selected": true,
"display": {
"brand": "VISA",
"last_digits": "4242",
"description": "Visa •••• 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\":\"...\",\"intermediateSigningKey\":{\"signedKey\":\"...\",\"signatures\":[\"...\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"...\\\",\\\"ephemeralPublicKey\\\":\\\"...\\\",\\\"tag\\\":\\\"...\\\"}\"}"
}
}
]
},
"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
`instrument.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.
