# Accept a payment via Google AI 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. --- ## Before you start You need: - A [test account](https://www.checkout.com/get-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](https://developers.google.com/merchant/ucp/guides). --- ## How it works 1. Your customers interact with Google's AI surfaces to browse products and initiate checkout. 2. Google's AI agent sends a request, including item and customer address data, to your server to create a checkout session. 3. Your server returns the initialized session, including order data such as payment amount and shipping options. 4. 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. 5. The customer selects to pay with Google Pay and authorizes the purchase via the payment sheet. 6. Google's AI agent sends a request to your server to complete the checkout session, including the encrypted Google Pay token. 7. Your server requests a Google Pay payment via Checkout.com, using the encrypted token. 8. Checkout.com returns the payment result. 9. Your server returns confirmation of the processed payment to Google's AI agent. 10. Google's AI agent shows an order confirmation to the customer. 11. Your server pushes post-purchase status updates to Google's unique webhook endpoint, so the customer can stay informed on their order fulfillment. ![Diagram of the purchase process when using agentic commerce with Google AI, showing the communication between your customer, Google, your MCP server, and the Checkout.com server.](https://www.checkout.com/docs/NAS/Flow/agentic_commerce_ucp_flow.png) --- ## Implement the Universal Commerce Protocol 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 | ### Configure your UCP payment handler 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](https://developers.google.com/pay/api/universal-commerce-protocol/google-pay-payment-handler). ### Google Pay payment handler declaration example ```json { "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": "The Online Retailer", "merchant_id": "KWMZPRLQFTYNXSDB", "merchant_origin": "merchant.example.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": "checkoutltd", "gatewayMerchantId": "pk_sbox_o2nulev4vbo43i4qkb5p7lfijap" } } } ] } } ] } } ``` ### Tokenize the Google Pay payment data 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](https://developers.google.com/merchant/ucp/guides/risk-signals) about the customer, which you can use for fraud detection. ### Google complete checkout session request example ```json { "payment": { "instruments": [ { "billing_address": { "first_name": "Jia", "last_name": "Tsang", "street_address": "654 Main St.", "address_locality": "Anytown", "address_region": "WY", "postal_code": "332211", "address_country": "US" }, "credential": { "type": "PAYMENT_GATEWAY", "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}" }, "display": { "brand": "VISA", "description": "Visa •••• 1234", "last_digits": "1234" }, "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c", "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2", "selected": true, "type": "CARD" } ] }, "signals": {} } ``` When you receive this request from Google: 1. Validate that the `handler_id` corresponds to that of your Google Pay payment handler. 2. Extract the encrypted payment data from the `credential.token` property of the Google Pay instrument. 3. Call the [Request a token](https://api-reference.checkout.com/tag/Tokens/#operation/requestAToken) endpoint to tokenize the encrypted payment data via Checkout.com, using the fields from `credential.token` to populate the `token_data` [object](https://api-reference.checkout.com/tag/Tokens#operation/requestAToken!path=1/token_data&t=request). > **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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/tokens` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/tokens` 3. Call the [Request a token](https://api-reference.checkout.com/tag/Tokens/#operation/requestAToken) endpoint to tokenize the encrypted payment data via Checkout.com, using the fields from credential.token to populate the token_data [[object]\{.underline}](https://api-reference.checkout.com/tag/Tokens#operation/requestAToken!path=1/token_data&t=request). > **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. ### Request example ```json { "type": "googlepay", "token_data": { "protocolVersion": "ECv2", "signature": "TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ", "signedMessage": "{\"encryptedMessage\": \"ZW5jcnlwdGVkTWVzc2FnZQ==\", \"ephemeralPublicKey\": \"ZXBoZW1lcmFsUHVibGljS2V5\", \"tag\": \"c2lnbmF0dXJl\"}" } } ``` ### Response example ```json { "type": "googlepay", "token": "tok_ubfj2q76miwundwlk72vxt2i7q", "expires_on": "2026-09-15T11:14:15Z" } ``` 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. ### Request a payment Call the [Request a payment](https://api-reference.checkout.com/tag/Payments#operation/requestAPaymentOrPayout) 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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` **Using the Checkout.com token** 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](#tokenize-the-google-pay-payment-data). ### Request example ```json { "source": { "type": "token", "token": "tok_ubfj2q76miwundwlk72vxt2i7q" }, "amount": 1000, "currency": "USD" } ``` **Using a pre-decrypted Google Pay token** 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)](https://www.checkout.com/docs/developer-resources/codes/eci-values.md) 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. ### Request example ```json { "source": { "type": "network_token", "token": "4242424242424242", "token_type": "googlepay", "expiry_month": "10", "expiry_year": "2027" }, "amount": 1000, "currency": "USD" } ``` ### Response example 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. --- ## Confirm the payment result 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. --- ## Send post-purchase order updates Follow [Google's instructions to push post-purchase order status updates](https://developers.google.com/merchant/ucp/guides/orders) to inform the customer about fulfillment. --- ## Test the integration To test Google Pay payments, first [create a test Checkout.com account](https://www.checkout.com/get-test-account). Google offers [mock test cards](https://developers.google.com/pay/api/android/guides/resources/test-card-suite#mock-testing), 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.