Overview

This guide shows how a Google AI agent (Google AI Mode or Gemini) transacts over Google's Universal Commerce Protocol (UCP) using the Google Pay payment handler and processes payments on the ACI Worldwide (OPPWA) platform.

The AI Agent (Platform) discovers the merchant's UCP profile, creates a checkout session, obtains a Google Pay token, submits that token as the UCP payment instrument, and the merchant backend charges the payment using ACI Worldwide.

AI Agent → UCP Checkout → Google Pay Token → /checkout-sessions/{id}/complete → ACI /v1/payments → Approved Transaction

Back to top

Architecture Diagram

The following sequence shows the interactions between the shopper, AI Agent (Platform), merchant, Google Pay, ACI Worldwide (OPPWA), and the acquirer / network.

Back to top

Step-by-Step Workflow

The AI Agent acquires a Google Pay token during checkout and submits it as the UCP payment instrument. The merchant backend then charges the transaction through ACI Worldwide. 【1-eef7b1】

1. The shopper finds and selects a product through the AI Agent (Platform).
2. The AI Agent retrieves the merchant's UCP profile using GET /.well-known/ucp.
3. The merchant returns the accepted payment handlers, including com.google.pay.
4. The AI Agent creates a checkout session using the shopper's cart.
5. The merchant returns the checkout state together with the Google Pay handler configuration.
6. The AI Agent requests payment data from Google Pay.
7. Google Pay displays the payment sheet.
8. The shopper selects the payment method and authorizes the payment.
9. Google Pay returns payment data containing the encrypted payment token.
10. The AI Agent submits the payment instrument using POST /checkout-sessions/{id}/complete.
11. The merchant backend sends a payment request to ACI Worldwide using POST /v1/payments.
12. ACI Worldwide decrypts and verifies the token.
13. ACI Worldwide submits the authorization / capture request to the acquiring side.
14. The acquirer / network returns the payment result.
15. ACI Worldwide returns the payment result to the merchant.
16. The merchant confirms the order and returns the order ID.
17. The AI Agent confirms the successful purchase to the shopper.

Back to top

Requirements

To follow this integration, accounts and approvals are required on the Google Pay side, the ACI Worldwide side, and the UCP integration side. 【1-eef7b1】

Google Pay

• Google Pay & Wallet Console account.
• Google Pay Merchant ID for the PRODUCTION environment.
• Google Pay API Terms of Service accepted.
• ACI Worldwide confirmed as the selected processor / gateway.

ACI Worldwide Side

• ACI account with an entityId.
• API access token for TEST and PRODUCTION.
• Configuration enabled for paymentBrand=GOOGLEPAY.
• Supported card networks enabled as required.
• TEST: https://eu-test.oppwa.com
• PRODUCTION: https://eu-prod.oppwa.com

UCP / Agent Side

• Merchant UCP profile published at /.well-known/ucp.
• Checkout endpoints including create, update and complete.
• Agent integrating both UCP and Google Pay.
• Server-side backend that submits the payment request to ACI Worldwide.

Back to top

Configure UCP Handler

Declare the com.google.pay handler in the UCP profile and specify tokenization_specification pointing to ACI so that Google encrypts the token for the ACI gateway. Return the same declaration in checkout responses. 【1-eef7b1】

The two important parameters that make this work are:

• gateway tells Google to encrypt the token so only ACI can decrypt it.
• gatewayMerchantId identifies your ACI Channel entity ID.

Return this same handler declaration in your UCP checkout responses so the agent uses the correct configuration and the platform enforces the right requirements per session. 【1-eef7b1】

{
  "payment_handlers": {
    "com.google.pay": [
      {
        "config": {
          "environment": "TEST",
          "merchant_info": {
            "merchant_id": "{{GOOGLE_PAY_MERCHANT_ID}}"
          },
          "allowed_payment_methods": [
            {
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "aciworldwide",
                  "gatewayMerchantId": "{{ACI_GATEWAY_ENTITY_ID}}"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

Back to top

Process Payment

Payment processing consists of two major stages:

1. The AI Agent obtains the encrypted Google Pay token and submits it through UCP.
2. The merchant backend submits the payment request to ACI Worldwide.

Get Encrypted Token from Google

The Google Pay API returns a PaymentData object. The encrypted token is available at paymentMethodData.tokenizationData.token. Pass this token on without modification. 【1-eef7b1】

paymentsClient.loadPaymentData(paymentDataRequest).then(function(paymentData) {
  const googlePayToken =
      paymentData.paymentMethodData.tokenizationData.token;

  submitToUcpComplete(googlePayToken);
});

Submit Instrument via UCP

The AI Agent maps the token into a UCP payment instrument and calls POST /checkout-sessions/{id}/complete. 【1-eef7b1】

The merchant receives the encrypted token inside the UCP Payment object. 【1-eef7b1】

POST /checkout-sessions/{id}/complete

Send Payment Request to ACI Worldwide

Submit the encrypted token using the standard OPPWA /v1/payments endpoint with paymentBrand=GOOGLEPAY. 【1-eef7b1】

POST https://eu-test.oppwa.com/v1/payments

entityId={{ACI_ENTITY_ID}}
paymentBrand=GOOGLEPAY
googlePay.paymentToken=<token>

Back to top

Result Codes

Treat the transaction as successful only when result.code matches an approved pattern. 【1-eef7b1】

#topBack to top

Test and Go Live

Test

• Set the handler environment to TEST.
• Use the TEST ACI endpoint.
• Use Google's test card suite or sample tokens.
• Verify token acquisition, UCP completion, ACI processing and result handling.
• Exercise approval, decline and pending scenarios.

Go Live

• Complete Google production onboarding and approvals.
• Switch the handler environment to PRODUCTION.
• Use the production Google Pay Merchant ID.
• Use production ACI credentials.
• Run a low-value live transaction end-to-end.
• Verify settlement and reporting before broad rollout.

#topBack to top