Accept a payment via Google AI

Last updated: September 9, 2026

Agentic commerce enables your customers to discover products and complete purchases through AI-powered chat interfaces, such as Google's AI Mode or Gemini. Integrating Checkout.com with Google's Universal Commerce Protocol (UCP) lets you accept payments within a conversational experience, without card data touching your servers.

Note

This integration only supports Google Pay PAN_ONLY payments.

You need:

A test account with Checkout.com.
Your public key, to use as the gatewayMerchantId value in your Google Pay payment handler.
A UCP profile on your server, accessible via /./.well-known/ucp,, with a Google Pay payment handler configured to accept payments via Checkout.com.
A Native Checkout API integration with Google's AI surfaces, following the Google UCP implementation guide.

Your customers interact with Google's AI surfaces to browse products and initiate checkout.
Google's AI agent sends a request, including item and customer address data, to your server to create a checkout session.
Your server returns the initialized session, including order data such as payment amount and shipping options.
Google's AI agent shows an order summary to the customer. At this stage, the customer can update their shipping address:
- If the shipping address is updated, Google's AI agent sends a request to your server to update the checkout session.
- Your server returns the updated checkout session, with recalculated amounts and shipping options as necessary.
The customer selects to pay with Google Pay and authorizes the purchase via the payment sheet.
Google's AI agent sends a request to your server to complete the checkout session, including the encrypted Google Pay token.
Your server requests a Google Pay payment via Checkout.com, using the encrypted token.
Checkout.com returns the payment result.
Your server returns confirmation of the processed payment to Google's AI agent.
Google's AI agent shows an order confirmation to the customer.
Your server pushes post-purchase status updates to Google's unique webhook endpoint, so the customer can stay informed on their order fulfillment.

Extend your server's UCP profile to handle the checkout session requests that Checkout.com's integration relies on.

Request Type	Endpoint	Description
Create a checkout session	`POST /checkout-sessions`	Initialize a new checkout with items and customer information
Complete a checkout session	`POST /checkout-sessions/{id}/complete`	Finalize the checkout and process payment

You must have a Google Pay payment handler configured in your UCP profile to accept payments via Checkout.com. Under tokenization_specification,, set:

type set to PAYMENT_GATEWAY
gateway set to checkoutltd
gatewayMerchantId set to your public key

You must also provide the payment handler declaration in your server's API response when Google calls POST /checkout-sessions to create a checkout session. This ensures that the correct payment options are available, and that necessary requirements are enforced for each checkout session.

For more information, see the Google Pay payment handler reference.


1{
2  "payment_handlers": {
3    "com.google.pay": [
4      {
5        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
6        "version": "2026-01-23",
7        "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
8        "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
9        "config": {
10          "api_version": 2,
11          "api_version_minor": 0,
12          "environment": "TEST",
13          "merchant_info": {
14            "merchant_name": "The Online Retailer",
15            "merchant_id": "KWMZPRLQFTYNXSDB",
16            "merchant_origin": "merchant.example.com"
17          },
18          "allowed_payment_methods": [
19            {
20              "type": "CARD",
21              "parameters": {
22                "allowed_auth_methods": [ "PAN_ONLY" ],
23                "allowed_card_networks": [
24                  "AMEX",
25                  "DISCOVER",
26                  "JCB",
27                  "MASTERCARD",
28                  "VISA"
29                ],
30                "billing_address_required": true,
31                "billing_address_parameters": {
32                  "format": "FULL",
33                  "phone_number_required": true
34                }
35              },
36              "tokenization_specification": {
37                "type": "PAYMENT_GATEWAY",
38                "parameters": {
39                  "gateway": "checkoutltd",
40                  "gatewayMerchantId": "pk_sbox_o2nulev4vbo43i4qkb5p7lfijap"
41                }
42              }
43            }
44          ]
45        }
46      }
47    ]
48  }
49}

When the customer authorizes their purchase via Google Pay, Google's AI agent calls your server with a POST /checkout-sessions/{id}/complete request, containing the encrypted payment data.

The request also contains any risk signals about the customer, which you can use for fraud detection.


1{
2  "payment": {
3    "instruments": [
4      {
5        "billing_address": {
6          "first_name": "Jia",
7          "last_name": "Tsang",
8          "street_address": "654 Main St.",
9          "address_locality": "Anytown",
10          "address_region": "WY",
11          "postal_code": "332211",
12          "address_country": "US"
13        },
14        "credential": {
15          "type": "PAYMENT_GATEWAY",
16          "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
17        },
18        "display": {
19          "brand": "VISA",
20          "description": "Visa •••• 1234",
21          "last_digits": "1234"
22        },
23        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
24        "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
25        "selected": true,
26        "type": "CARD"
27      }
28    ]
29  },
30  "signals": {}
31}

When you receive this request from Google:

Validate that the handler_id corresponds to that of your Google Pay payment handler.
Extract the encrypted payment data from the credential.token property of the Google Pay instrument.
Call the Request a token endpoint to tokenize the encrypted payment data via Checkout.com, using the fields from credential.token to populate the token_data object.

Note

To process Google Pay transactions, you must authenticate your request using the same public key you provided in your Google Pay payment handler's tokenization_specification.gatewayMerchantId field.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/tokens

Call the Request a token endpoint to tokenize the encrypted payment data via Checkout.com, using the fields from credential.token to populate the token_data [object]{.underline}.

Note


1{
2  "type": "googlepay",
3  "token_data": {
4    "protocolVersion": "ECv2",
5    "signature": "TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
6    "signedMessage": "{\"encryptedMessage\": \"ZW5jcnlwdGVkTWVzc2FnZQ==\", \"ephemeralPublicKey\": \"ZXBoZW1lcmFsUHVibGljS2V5\", \"tag\": \"c2lnbmF0dXJl\"}"
7  }
8}


1{
2  "type": "googlepay",
3  "token": "tok_ubfj2q76miwundwlk72vxt2i7q",
4  "expires_on": "2026-09-15T11:14:15Z"
5}

Use the token value from the token field in your payment request.

Note

Google's AI surfaces currently only support Google Pay's PAN_ONLY authorization method, which does not provide liability shift.

Call the Request a payment endpoint, setting the following fields, depending on the token format you want to use:

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments

To request a payment using the Checkout.com token, set the following fields:

source.type set to token
token set to the value of the token field from the response you got when you tokenize the Google Pay payment data.


1{
2  "source": {
3    "type": "token",
4    "token": "tok_ubfj2q76miwundwlk72vxt2i7q"
5  },
6  "amount": 1000,
7  "currency": "USD"
8}

Checkout.com supports payments using Google Pay tokens that you have decrypted. To use this feature, set the following fields:

source.type set to network_token
token_type set to googlepay

This source type lets you provide the token details, as well as the cryptogram and Electronic Commerce Indicator (ECI) value obtained from the Google Pay token.

Note

To decrypt the Google Pay token yourself, set tokenizationSpecification.type to DIRECT when you retrieve the Google Pay payment data.


1{
2  "source": {
3    "type": "network_token",
4    "token": "4242424242424242",
5    "token_type": "googlepay",
6    "expiry_month": "10",
7    "expiry_year": "2027"
8  },
9  "amount": 1000,
10  "currency": "USD"
11}

If the approved field is true, your authorization was successful. A failed authorization can indicate the payment used an invalid or expired card, or a card with an insufficient available balance.

A successful response includes a payment_account_reference value, which is a unique reference to the underlying card for network tokens. If the card scheme provides an eci value, the response includes it. The value indicates the security level that the card scheme decided to request the payment with.

Once you successfully process the payment, return a response to Google to indicate that the order is complete. Include the order ID and a permalink URL to the order.

Follow Google's instructions to push post-purchase order status updates to inform the customer about fulfillment.

To test Google Pay payments, first create a test Checkout.com account.

Google offers mock test cards, which you can add to your wallet.

If you perform a payment with a real card in Google's sandbox environment, Google Pay provides a test card in the encrypted payment data. No actual charge takes place.

Accept a payment via Google AI

Note

Before you start

How it works

Implement the Universal Commerce Protocol

Configure your UCP payment handler

Google Pay payment handler declaration example

Tokenize the Google Pay payment data

Google complete checkout session request example

Note

Information

Note

Request example

Response example

Note

Request a payment

Information

Request example

Note

Request example

Response example

Confirm the payment result

Send post-purchase order updates

Test the integration