## 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](https://developers.google.com/pay/api#participating-processors) (PSPs) around the world.

> [!NOTE]
> **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](https://developers.google.com/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](https://developers.google.com/pay/api#participating-processors) 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

> [!NOTE]
> **Note:** You can use the [UCP code
> generator](https://developers.google.com/pay/api/universal-commerce-protocol/reference/code-generator) to create the payment handler declaration for your UCP profile and checkout responses.

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](https://developers.google.com/pay/api/universal-commerce-protocol/reference/config). |

##### 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](https://developers.google.com/merchant/ucp/guides/ucp-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](https://ucp.dev/2026-04-08/specification/checkout/#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](https://developers.google.com/pay/api/universal-commerce-protocol/reference/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](https://pay.google.com/business/console/) account
with production access. For more information, see [Prepare for
production](https://developers.google.com/pay/api/universal-commerce-protocol/prepare-for-production).