--- title: Universal Commerce Protocol integration with Braintree --- # Universal Commerce Protocol integration with Braintree (/agent-ready/universal-commerce-protocol-with-braintree) Use this guide to integrate the Google Pay payment handler for Google's Universal Commerce Protocol (UCP) with Braintree as your payment provider. This enables AI-powered checkout experiences through Google AI Mode (Gemini), where Google Pay returns a tokenized credential that Braintree can process, and your server uses it to process the payment. ## How it works [#how-it-works] In a standard Google Pay integration, tokenization happens client-side. With UCP, Google shifts this to the server side. The following table shows the key differences. | Integration detail | Standard integration | UCP or AI mode integration | | ------------------------- | ------------------------------------- | ----------------------------------------------- | | Client SDK | Required in your web or mobile client | Not used in your client | | Tokenization | Performed client-side through SDK | Google handles tokenization on server side | | Single-use token delivery | SDK returns to client | Google includes it in checkout-complete payload | | Parsing | SDK parses automatically | Merchant parses `androidPayCards` JSON | Using Google's UCP, AI agents can: * Discover your products through your product catalog. * Create checkout sessions through the UCP specification. * Send the tokenized Braintree payment, including the tokenized credential, to your server to complete checkout. ## Prerequisites [#prerequisites] * Active Braintree merchant account. * Google Pay enabled in your Braintree Control Panel. * UCP merchant registration with Google. Contact Google for enablement. * Familiarity with Braintree's `Transaction.sale` or `chargePaymentMethod` GraphQL mutation. ## Step 1: Configure Google Pay payment handler tokenization [#step-1-configure-google-pay-payment-handler-tokenization] When registering your UCP profile with Google, you will define a full Google Pay payment handler specification. The following `tokenizationSpecification` block is the Braintree-specific section that belongs inside the `allowed_payment_methods` entry of that specification. For more information, see the [Google Pay payment handler specification](https://developers.google.com/merchant/ucp/guides/google-pay-payment-handler). ```json [expandable] { "payment_handlers": { "com.google.pay": [ { "id": "YOUR_HANDLER_UUID", "name": "com.google.pay", "version": "2026-01-23", "config": { "api_version": 2, "api_version_minor": 0, "environment": "PRODUCTION", "merchant_info": { "merchant_name": "YOUR_BUSINESS_NAME", "merchant_id": "YOUR_GOOGLE_MERCHANT_ID", "merchant_origin": "checkout.yourdomain.com" }, "allowed_payment_methods": [ { "type": "CARD", "parameters": { "allowed_auth_methods": ["PAN_ONLY"], "allowed_card_networks": [ "AMEX", "DISCOVER", "MASTERCARD", "VISA" ], "billingAddressRequired": true, "billingAddressParameters": { "format": "FULL", "phoneNumberRequired": false } }, "tokenizationSpecification": { "type": "PAYMENT_GATEWAY", "parameters": { "gateway": "braintree", "braintree:apiVersion": "v1", "braintree:sdkVersion": "BRAINTREE_SDK_VERSION", "braintree:merchantId": "YOUR_BRAINTREE_MERCHANT_ID", "braintree:clientKey": "YOUR_BRAINTREE_TOKENIZATION_KEY" } } } ] } } ] } } ``` | Parameter | Description | | ---------------------- | ---------------------------------------------------- | | `gateway` | Set to `braintree` | | `braintree:apiVersion` | API version (`v1`) | | `braintree:sdkVersion` | Braintree-web SDK version string such as `"3.136.0"` | | `braintree:merchantId` | Your Braintree public merchant ID | | `braintree:clientKey` | Your Braintree tokenization key | > **Info:** > * `braintree:clientKey` requires a tokenization key. See the [Braintree > > tokenization key > > documentation](https://developer.paypal.com/braintree/docs/guides/authorization/tokenization-key/javascript/v3/#obtaining-a-tokenization-key) > > for details. > - `braintree:sdkVersion` value comes from the merchant's pinned > > braintree-web dependency or npm. The system uses it for telemetry and > > observability only and doesn't affect tokenization or payment behavior. ## Step 2: Handle the checkout payload [#step-2-handle-the-checkout-payload] When Google calls your `/checkout-session/{id}/complete` endpoint, the payment payload includes the Braintree single-use token in the `credential.token` field. **Expected payload structure** ```json [expandable] { "payment": { "instruments": [ { "id": "pm_1234567890abc", "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c", "type": "card", "display": { "brand": "visa", "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": "{\"androidPayCards\":[{\"\":\"bd4c9b33-6e1c-11d8-1f4b-c0117fad06f7\",\"description\":\"Android Pay\",\"details\":{\"bin\":\"411111\",\"cardType\":\"Visa\",\"lastFour\":\"4242\"}}]}" } } ] }, "risk_signals": {} } ``` **Parsing the single-use token** The `credential.token` contains a JSON string with the `androidPayCards` array. Parse it to extract the single-use token. ```javascript // Parse the token from Google's checkout complete payload const tokenData = JSON.parse(payment.instruments[0].credential.token); const nonce = tokenData.androidPayCards[0].nonce; // Use the nonce with Braintree console.log(nonce); // "bd4c9b33-6e1c-11d8-1f4b-c0117fad06f7" ``` ## Step 3: Process the payment with Braintree [#step-3-process-the-payment-with-braintree] Use the extracted single-use token exactly as you would any other Braintree payment method. **Using Braintree SDK (Node.js)** ```javascript [expandable] const result = await gateway.transaction.sale({ amount: "10.00", paymentMethodNonce: nonce, options: { submitForSettlement: true, }, }); if (result.success) { console.log("Transaction ID:", result.transaction.id); } else { console.error("Transaction failed:", result.message); } ``` **Using GraphQL** ```graphql [expandable] mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) { chargePaymentMethod(input: $input) { transaction { id status amount { value currencyCode } } } } ``` **Variables** ```json [expandable] { "input": { "paymentMethodId": "bd4c9b33-6e1c-11d8-1f4b-c0117fad06f7", "transaction": { "amount": "10.00" } } } ``` **Vaulting considerations** If you need to vault the Google Pay payment method for recurring transactions: ```javascript [expandable] const result = await gateway.customer.create({ firstName: "Jane", lastName: "Smith", paymentMethodNonce: nonce, }); if (result.success) { const paymentMethodToken = result.customer.paymentMethods[0].token; // Store this token for future transactions } ``` > **Warning:** Review [Google Pay's terms](https://developers.google.com/pay/api/faq) > regarding vaulting network-tokenized cards and FPAN-based cards. Braintree > treats the Google Pay-derived credential as a single-use payment method that > may only be used once and expires after 3 hours if unused, so avoid flows that > try to both charge and vault the same value. ## Troubleshooting [#troubleshooting] Use the following information to diagnose and resolve common integration issues. ### Common errors [#common-errors] | Error | Cause | Solution | | ---------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ | | `Unknown or expired single-use payment method` | Single-use token expired or wrong merchant ID | Verify merchant ID matchesSingle-use tokens expire after use | | Empty `androidPayCards` array | Tokenization failed | Verify tokenization key and merchant ID configuration. | ### Verify your configuration [#verify-your-configuration] * Confirm the Braintree merchant ID is correct on your UCP Google Pay payment handler definition in the `tokenizationSpecification` section. * Verify the tokenization key is valid and not expired. * Ensure Google Pay is enabled in the Braintree Control Panel.