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 modelwhere 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 Prerequisites

To use this handler, first set up your business with Google Pay .

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

By default, Google Pay may only return a partial billing address (e.g., ZIP code and country). To request the full billing address, you can include the optional the billing_address_required and billing_address_parameters within the parameters object for the CARD type payment method.

Set billing_address_required to true , and specify format : "FULL" within billing_address_parameters . You can also request the phone number by setting phone_number_required : true . If these fields are not included, the default Google Pay behavior for billing address information will apply.

See the example for the implementation.

  { 
  
 "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" 
  
 } 
  
 } 
  
 } 
  
 ] 
  
 } 
  
 } 
  
 ] 
  
 } 
 }

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 level of detail depends on the `billing_address_parameters` in the configuration.
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 
  
 /checkou 
 t 
 - 
 sessio 
 ns 
 / 
 { 
 checkou 
 t 
 _id 
 } 
 /comple 
 te 
 { 
  
 "payment" 
 : 
  
 { 
  
 "instruments" 
 : 
  
 [ 
  
 { 
  
 "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\"...}" 
  
 } 
  
 } 
  
 ] 
  
 }, 
  
 "risk_signals" 
 : 
  
 { 
  
 // ... risk data 
  
 } 
 }

4. Business Processing

Upon receiving a Google Pay payment instrument, businesses MUST:

Validate handler:Confirm handler_id corresponds to the Google Pay payment handler.
Extract token:Retrieve the generated payment method token from payment_data.credential.token .
Process payment:Use the token and transaction details to complete payment. Refer to Google Pay API documentation for detailed documentation on tokenization specification and handling.
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.

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