Google Pay™ Integration#

Seamless payment processing with Google’s trusted platform

Merchant policy requirements: Merchants must adhere to the Google Pay and Wallet APIs Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service .

Google Pay Web developer documentation: This guide covers the Lesaka-specific parts of a Google Pay integration. For Google’s complete guidance on integrating Google Pay into a website, see the Google Pay Web developer documentation .

Quick Navigation#

• Overview
• Gateway Flow
• Merchant Flow
• Setup Steps
• Visa Liability Shift
• Authentication Methods & 3D Secure
• Billing Address Requirements
• Supported Networks, Currencies & Settlement
• Security
• Implementation

Integration Overview#

Choose from two powerful integration methods to implement Google Pay with Lesaka’s payment gateway:

Gateway Decryption Flow — Recommended#

The merchant acquires the token, then sends the encrypted payload received from Google to Lesaka for decryption and processing.

Benefits:

• Faster Implementation
• Enhanced Security
• Reduced Compliance

View Implementation →

Merchant Decryption Flow — Advanced#

The merchant acquires and decrypts the token received from Google, then sends the decrypted details to Lesaka for processing.

Benefits:

• Full Control
• Custom Validation
• Direct Processing

View Implementation →

Method 1: Gateway Decryption Flow#

Recommended

Process Flow#

    sequenceDiagram
    participant C as Customer
    participant GP as Google Pay
    participant M as Merchant
    participant AG as Lesaka Gateway
    participant CN as Card Network
    
    C->>GP: Initiate Payment
    GP->>GP: Generate Encrypted Token
    GP->>M: Return Encrypted Token
    M->>AG: Send Encrypted Token
    AG->>AG: Decrypt Token
    AG->>CN: Process Payment
    CN->>AG: Payment Response
    AG->>M: Transaction Result
    M->>C: Payment Confirmation
  

Step-by-Step#

1. Customer Initiates Payment — Customer selects Google Pay as payment method.
2. Token Generation — Google Pay returns encrypted payment token to merchant.
3. Token Forwarding — Merchant forwards encrypted token directly to Lesaka.
4. Processing & Response — Lesaka decrypts token, processes payment, and returns result.

Google Pay Configuration#

Configure your Google Pay payment request with the correct tokenization specification and merchant information for Gateway Decryption Flow.

Tokenization Specification (Required):

tokenizationSpecification: {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    gateway: 'adumoonline',
    gatewayMerchantId: 'YOUR_LESAKA_APPLICATION_UID'
  }
}

Merchant Information#

Required

merchantInfo: {
  merchantId: 'YOUR_GOOGLE_PAY_MERCHANT_ID', // Example: BXF2DN4T236LPQ6RE
  merchantName: 'YOUR_BUSINESS_NAME'
}

Configuration Values Reference#

Complete Google Pay Request Example#

const paymentDataRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [{
    type: 'CARD',
    parameters: {
      allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
      allowedCardNetworks: ['MASTERCARD', 'VISA'],
      billingAddressRequired: true,
      billingAddressParameters: {
        format: 'MIN',
        phoneNumberRequired: true
      }
    },
    tokenizationSpecification: {
      type: 'PAYMENT_GATEWAY',
      parameters: {
        gateway: 'adumoonline',
        gatewayMerchantId: '23ADADC0-DA2D-4DAC-A128-4845A5D71293' // Replace with Production Lesaka ApplicationUID when going live
      }
    }
  }],
  merchantInfo: {
    merchantId: 'BXF2DN4T236LPQ6RE', // Replace with your own Google Merchant ID when going live
    merchantName: 'Example Merchant Trading Name'
  },
  emailRequired: true,
  transactionInfo: {
    totalPriceStatus: 'FINAL',
    totalPriceLabel: 'Total',
    totalPrice: '100.00',
    currencyCode: 'ZAR',
    countryCode: 'ZA',
    checkoutOption: 'DEFAULT'
  }
};

Setup Steps#

1. Register with Google Pay#

Complete merchant registration in the Google Pay Business Console .

2. Obtain Merchant ID#

Copy your Google Pay Merchant ID from
Console → Settings → Merchant Profile
Open Google Pay Console

3. Configure Environment#

Set up your environment variables with the merchant details.
See the Google Pay Configuration section for detailed instructions.

4. Test Integration#

Use Lesaka’s staging environment before going live. Download the Postman Collection for testing examples.

Additional Resources#

• Google Pay Web Developer Documentation
• Google Pay API Reference
• Integration Tutorial
• Google Pay Web Integration Checklist
• Brand Guidelines
• Publish Your Integration

API Endpoint#

POST /products/payments/v1/card/google-pay/initiate

Example Payload with Encrypted Token#

{
  "applicationUid": "23ADADC0-DA2D-4DAC-A128-4845A5D71293",
  "merchantUid": "9BA5008C-08EE-4286-A349-54AF91A621B0",
  "value": 100.00,
  "merchantReference": "GP-REF-123456",
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0...",
  "paymentDataResponse": {
    "apiVersion": 2,
    "apiVersionMinor": 0,
    "email": "john.doe@example.com",
    "paymentMethodData": {
      "description": "Visa •••• 1111",
      "type": "CARD",
      "info": {
        "cardNetwork": "VISA",
        "cardDetails": "1111",
        "cardFundingSource": "CREDIT",
        "billingAddress": {
          "name": "John Doe",
          "countryCode": "ZA",
          "postalCode": "8001",
          "phoneNumber": "+27821234567"
        }
      },
      "tokenizationData": {
        "type": "PAYMENT_GATEWAY",
        "token": "eyJlbmNyeXB0ZWRNZXNzYWdlIjoiQUVTL0dDTS8yNTYvSElUQUcvOTYvSVYvMTI4L1BBRERJTkcvUEtDUzFQQURESU5HIiwiZXBoZW1lcmFsUHVibGljS2V5IjoiQk..."
      }
    }
  }
}

Advantages#

• Lesaka manages token decryption and payment processing
• Reduced PCI DSS scope and cryptographic key-management responsibility
• Simpler implementation and faster time to market
• No merchant-side Google Pay token decryption infrastructure required

Considerations#

• Encrypted Google Pay tokens must be forwarded to Lesaka without modification
• Token decryption and processing depend on Lesaka’s gateway availability and configuration
• Merchants have less control over token validation and decryption
• Merchants must configure and manage Visa liability protection in their own Google Pay & Wallet Console

Method 2: Merchant Decryption Flow#

Process Flow#

    sequenceDiagram
    participant C as Customer
    participant GP as Google Pay
    participant M as Merchant
    participant AG as Lesaka Gateway
    participant CN as Card Network

    C->>GP: Initiate Payment
    GP->>GP: Generate Encrypted Token
    GP->>M: Return Encrypted Token
    M->>M: Decrypt Token (Extract Card Details)
    M->>AG: Send Decrypted Card Data
    AG->>CN: Process Payment
    CN->>AG: Payment Response
    AG->>M: Transaction Result
    M->>C: Payment Confirmation
  

Step-by-Step#

1. Customer Initiates Payment Customer selects Google Pay as payment method.

2. Token Generation Google Pay returns encrypted payment token to the merchant.

3. Token Decryption Merchant verifies and decrypts the ECv2 token. Google recommends the Java Tink paymentmethodtoken library; other languages must implement Google’s documented ECv2 protocol.

4. Processing & Response Merchant sends decrypted card details to Lesaka for processing.

Google Pay DIRECT Configuration#

Important: To use the Merchant Decryption Flow, configure Google Pay with tokenizationSpecification.type: 'DIRECT' instead of 'PAYMENT_GATEWAY'.

Tokenization Specification#

tokenizationSpecification: {
  type: 'DIRECT',
  parameters: {
    protocolVersion: 'ECv2',
    publicKey: 'YOUR_PUBLIC_KEY_HERE'
  }
}

Requirements#

DIRECT integration eligibility: DIRECT integration is available only to PCI DSS-compliant merchants handling their own payment credentials. Third-party PSPs and platforms may not use DIRECT to decrypt credentials on behalf of merchants; they must use an approved gateway or hosted-checkout integration.

For full details on protocolVersion and publicKey setup, refer to:
Google Pay DIRECT Integration Reference

Configuration Values Reference#

Complete Google Pay Request Example#

const paymentDataRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [{
    type: 'CARD',
    parameters: {
      allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
      allowedCardNetworks: ['MASTERCARD', 'VISA'],
      billingAddressRequired: true,
      billingAddressParameters: {
        format: 'MIN',
        phoneNumberRequired: true
      }
    },
    tokenizationSpecification: {
      type: 'DIRECT',
      parameters: {
        protocolVersion: 'ECv2',
        publicKey: 'YOUR_PUBLIC_KEY_HERE' // Replace with your actual public key
      }
    }
  }],
  merchantInfo: {
    merchantId: 'BXF2DN4T236LPQ6RE', // Replace with your Google Merchant ID
    merchantName: 'Example Merchant Trading Name'
  },
  emailRequired: true,
  transactionInfo: {
    totalPriceStatus: 'FINAL',
    totalPriceLabel: 'Total',
    totalPrice: '100.00',
    currencyCode: 'ZAR',
    countryCode: 'ZA',
    checkoutOption: 'DEFAULT'
  }
};

Setup Steps#

1. Register with Google Pay Create a merchant account at the Google Pay Business Console and configure for DIRECT integration.

2. Generate Key Pair Create a public/private key pair for token decryption and register the public key with Google Pay.

3. Implement Decryption Implement ECv2 signature verification and token decryption. For Java, use Google’s recommended Tink paymentmethodtoken library; for other languages, follow Google’s ECv2 cryptography specification. Refer to the Configuration section .

4. Test Integration Test with decrypted card data using Lesaka’s staging environment. Download the Postman Collection for testing examples.

Additional Resources#

• Google Pay Web Developer Documentation
• Google Pay DIRECT API Reference
• Payment Data Cryptography
• Brand Guidelines
• Publish Your Integration

API Endpoint#

POST /products/payments/v1/card/initiate

Example Payload with Decrypted Token#

{
  "applicationUid": "23ADADC0-DA2D-4DAC-A128-4845A5D71293",
  "merchantUid": "9BA5008C-08EE-4286-A349-54AF91A621B0",
  "value": 100.00,
  "merchantReference": "GP-REF-123456",
  "cardNumber": "4111111111111111",
  "expiryMonth": 12,
  "expiryYear": 2025,
  "cardHolderFullName": "John Doe",
  "cardHolderEmailAddress": "john.doe@example.com",
  "description": "Google Pay Payment",
  "saveCardDetails": true,
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0...",
  "tokenDetails": {
    "tokenProvider": "GOOGLE_PAY",
    "networkToken": true,
    "cryptogram": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
    "eci": "05",
    "originalPanBin": "411111",
    "originalPanLast4": "1111"
  }
}

This example is for a CRYPTOGRAM_3DS credential. For a PAN_ONLY credential omit tokenDetails entirely — see Authentication Methods & 3D Secure .

Advantages#

• Full control over token decryption
• Ability to validate tokens before sending to gateway
• Reduced dependency on external gateways
• Allows for custom token validation logic

Considerations#

• Complex key and certificate management
• Requires ECv2 signature verification and token decryption; Google’s recommended Tink implementation is Java-only
• Merchant must handle sensitive card data
• PCI DSS compliance required

Visa Liability Shift#

Visa liability protection applies to both integration flows. Merchants using either the Gateway Decryption Flow or the Merchant Decryption Flow (DIRECT) are responsible for configuring and managing it in their own Google Pay & Wallet Console.

Google Pay supports liability shift for qualified Mastercard and Visa Android device-token transactions that use CRYPTOGRAM_3DS, subject to card-network rules. Qualified Mastercard device-token transactions receive liability shift automatically. For eligible Visa integrations, merchants using either flow must enable Fraud Liability Protection for Visa Device Tokens in their own Console where applicable.

Enable Visa Liability Shift#

1. Sign in to the Google Pay & Wallet Console .
2. Open the Google Pay API tab.
3. Open the Settings tab.
4. Enable Fraud Liability Protection for Visa Device Tokens.

Feature settings are available for approved Android or Web integrations. European merchants are automatically covered by a Visa exception for eligible transactions made with cards issued by European issuers.

Integration Requirements#

• Send the actual, non-zero transaction amount in transactionInfo.totalPrice and the correct authorization currency in transactionInfo.currencyCode.
• Merchants using either flow must manage Visa liability protection in their own Google Pay & Wallet Console.
• For the Gateway Decryption Flow, forward the encrypted Google Pay token to Lesaka Online without modification. Lesaka Online decrypts the token for processing.
• For the Merchant Decryption Flow, pass the eciIndicator from the decrypted Google Pay payload to Lesaka Online without altering it.
• For a Merchant Decryption Flow (DIRECT) integration, liability-shift status is available through the eciIndicator in the decrypted payment data.
• Google Pay web transactions that use the optional OFFER callback intent do not qualify for Visa liability shift.

For eligibility details, exclusions, and current network requirements, see Google’s Shift liability to issuer guide.

Authentication Methods & 3D Secure#

Google Pay returns one of two authentication methods in the decrypted payment credential. The method returned depends on the customer’s device and how the card was added to Google Pay — the merchant cannot choose which one is returned, only which ones are accepted via allowedAuthMethods.

Key point: A PAN_ONLY credential is not authenticated by Google. It carries the same fraud and chargeback exposure as a customer typing their card number into a form. To obtain issuer authentication (and, where applicable, liability shift) for PAN_ONLY transactions, the transaction must go through Lesaka’s standard 3D Secure flow.

Enabling 3D Secure for PAN_ONLY credentials#

3D Secure for PAN_ONLY is controlled by the applicationUid you send to Lesaka, in exactly the same way as for a normal card transaction. There is no Google Pay-specific flag on the request and no separate merchant setting:

• Use a 3D Secure-enabled ApplicationUID and Lesaka will perform the 3DS lookup on every PAN_ONLY credential. Where the issuer participates, the initiate response returns threeDSecureAuthRequired: true together with the acsUrl, acsPayload and acsMD needed to redirect the cardholder to their bank.
• Use a non-3D Secure ApplicationUID and PAN_ONLY credentials are authorised without issuer authentication.

For the staging environment, the 3D Secure-enabled test ApplicationUID is 23ADADC0-DA2D-4DAC-A128-4845A5D71293 and the non-3D Secure one is 904A34AF-0CE9-42B1-9C98-B69E6329D154 (see Test Account Details ). For production, request a 3D Secure-enabled ApplicationUID from Lesaka support if your account does not already have one.

CRYPTOGRAM_3DS credentials are not sent through 3D Secure regardless of ApplicationUID. The presence of a cryptogram tells Lesaka that the card network has already authenticated the transaction: the cryptogram is passed to the acquirer as the CAVV, and the eciIndicator supplied by Google is passed through unaltered. If Google omits eciIndicator, Lesaka defaults it to 02 for Mastercard and 05 for all other networks.

Applications configured for external (merchant-managed) 3D Secure cannot use /card/google-pay/initiate, because the Google Pay initiate request has no way to carry an external 3DS result. Use an application configured for Lesaka-managed 3D Secure, or use the Merchant Decryption Flow with /card/initiate.

How the flow differs by integration method#

Gateway Decryption Flow (PAYMENT_GATEWAY)

1. Forward the encrypted token to POST /products/payments/v1/card/google-pay/initiate using a 3D Secure-enabled applicationUid.
2. Lesaka decrypts the token and inspects authMethod.
   • CRYPTOGRAM_3DS → the response returns threeDSecureAuthRequired: false and you proceed straight to Authorise .
   • PAN_ONLY → Lesaka performs the 3DS lookup. If the issuer participates, the response returns threeDSecureAuthRequired: true plus acsUrl, acsPayload and acsMD.
3. When threeDSecureAuthRequired is true, POST the cardholder to the acsUrl and complete the challenge exactly as described in the 3D Secure section of the Enterprise guide, then call Authenticate and Authorise .

The /card/google-pay/initiate response has the same structure as the standard /card/initiate response — see Response Handling below.

Merchant Decryption Flow (DIRECT)

1. Decrypt the token and read paymentMethodDetails.authMethod.
2. PAN_ONLY → send the decrypted pan, expirationMonth and expirationYear to POST /products/payments/v1/card/initiate as cardNumber, expiryMonth and expiryYear, using a 3D Secure-enabled applicationUid. Do not include a tokenDetails object — there is no cryptogram for a PAN_ONLY credential, and supplying an empty or fabricated cryptogram/eci would cause Lesaka to skip 3D Secure. Lesaka treats the transaction as a standard card-not-present initiate and returns threeDSecureAuthRequired as described above.
3. CRYPTOGRAM_3DS → send the decrypted pan, expiry, and a tokenDetails object as shown in the Example Payload with Decrypted Token . No 3DS challenge is performed.

   tokenDetails field	Value	Required
   tokenProvider	"GOOGLE_PAY"	Yes
   networkToken	true	Yes
   cryptogram	paymentMethodDetails.cryptogram from the decrypted token (base64)	Yes
   eci	paymentMethodDetails.eciIndicator from the decrypted token, unaltered. If absent, use 02 for Mastercard, 05 otherwise	Yes
   originalPanBin	First 6 digits of the decrypted pan	Optional
   originalPanLast4	Last 4 digits of the decrypted pan	Optional

Restricting to CRYPTOGRAM_3DS only#

If you do not want to accept unauthenticated credentials at all, remove PAN_ONLY from allowedAuthMethods:

allowedAuthMethods: ['CRYPTOGRAM_3DS']

Be aware that this prevents customers on desktop browsers and on devices without a tokenised card from paying with Google Pay, which typically reduces conversion. Google’s guidance is to accept both methods and apply 3D Secure to PAN_ONLY where required.

Billing Address Requirements#

Request the cardholder’s billing address from Google Pay on every transaction. Lesaka uses it to populate the cardholder name and contact number on the transaction record, and merchants should retain it as supporting evidence in chargeback disputes and for their own fraud screening.

Address Verification (AVS): Lesaka does not perform AVS on Google Pay transactions in either flow. The billing address is not matched against the issuer’s records, and no AVS result is returned in any response. Do not rely on Lesaka for address-based verification of Google Pay payments.

Request the address from Google Pay#

Set billingAddressRequired: true on the CARD payment method in both integration flows. MIN format is sufficient for Lesaka; use FULL if your own fraud rules or fulfilment need street-level data.

parameters: {
  allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
  allowedCardNetworks: ['MASTERCARD', 'VISA'],
  billingAddressRequired: true,
  billingAddressParameters: {
    format: 'MIN',            // 'MIN' (minimum) or 'FULL'
    phoneNumberRequired: true
  }
}

Setting emailRequired: true at the top level of the request is also recommended so that the cardholder email is available for receipts and dispute evidence.

Forward the address to Lesaka#

Gateway Decryption Flow — forward the complete paymentDataResponse to /card/google-pay/initiate unmodified (see the Example Payload with Encrypted Token ). Lesaka reads the following from it:

The Gateway flow initiate request itself only uses applicationUid, merchantUid, value, merchantReference, ipAddress, userAgent, the optional multiCurrency object, and paymentDataResponse. Any other top-level fields (including billingDetails, cardHolderEmailAddress and saveCardDetails) are ignored on this endpoint — the card is always tokenised (saveCardDetails is forced to true) and the response therefore returns a cardToken and profileUid.

Merchant Decryption Flow — the billing address is not inside the encrypted token; it is in the clear-text paymentMethodData.info.billingAddress of the Google response. Map it onto the Initiate Transaction call. The /card/initiate request accepts the flat cardholder fields as well as an optional structured billingDetails object:

{
  "applicationUid": "…",
  "merchantUid": "…",
  "value": 100.00,
  "merchantReference": "GP-REF-123456",
  "cardNumber": "4111111111111111",
  "expiryMonth": 12,
  "expiryYear": 2028,
  "cardHolderFullName": "John Doe",
  "cardHolderEmailAddress": "john.doe@example.com",
  "cardholderContactNumber": "+27821234567",
  "billingDetails": {
    "address": {
      "address1": "14 Street Name",
      "city": "Cape Town",
      "province": "WC",
      "postalCode": "8001",
      "countryCode": "ZA"
    }
  },
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0…"
}

billingDetails is optional and all of its fields are free-text strings; it is stored against the transaction and forwarded to the acquirer where the acquirer accepts address data, but — as noted above — Lesaka does not perform or return an AVS check on it.

Minimum requirement#

At minimum, request the MIN format (name, postalCode, countryCode) plus phoneNumberRequired: true and emailRequired: true on every transaction. Transactions submitted without a billing address will still be processed, but:

• the cardholder name and contact number on the transaction will be recorded as Not Provided;
• the transaction may be declined by merchant-level fraud rules that require an address; and
• the merchant will have weaker evidence in the event of a “cardholder not recognised” chargeback.

Supported Networks, Currencies & Settlement#

Google Pay does not have its own acceptance rules on the Lesaka platform. Once the token is decrypted, the card is processed under exactly the same card configuration as a normal card transaction for the applicationUid you send — network acceptance, 3D Secure, trading currency and acquirer routing are all taken from that application. Values in the Google Pay request that fall outside your application’s configuration are declined by Lesaka at initiate.

Card networks#

Lesaka determines the network from the decrypted card number (BIN lookup) and checks it against the card types enabled for your application. There is no separate Google Pay network list.

Include in allowedCardNetworks only the networks that are enabled on your Lesaka application — for most merchants that is ['MASTERCARD', 'VISA']. If a network is listed in allowedCardNetworks but not enabled on your application, Google Pay will offer the card to the customer and Lesaka will decline it at initiate with <card type> card type not supported. Diners Club is accepted for standard card payments (see Test Cards ) but is not a Google Pay network.

Currency and country of settlement#

Multi-Currency Processing (MCP)#

Merchants enrolled for Multi-Currency Processing may charge the customer in a foreign currency while settling in the application’s trading currency. Both /card/google-pay/initiate and /card/initiate accept an optional multiCurrency object:

"multiCurrency": {
  "currencyCode": "USD",   // ISO 4217, 3 upper-case letters — the currency shown to the customer
  "value": 5.50            // amount in that currency, > 0
}

When multiCurrency is supplied, set Google Pay’s transactionInfo.currencyCode and totalPrice to the same foreign currency and amount so that the customer sees the correct figure. Current exchange rates for your application can be retrieved from POST /products/payments/v1/card/mcp-exchange-rates. If your account is not enrolled, the request fails with Merchant is not signed up for multi-currency processing — contact Lesaka support to enable MCP.

currencyCode and countryCode also affect liability shift: the value in transactionInfo.totalPrice and currencyCode must be the actual authorisation amount and currency (see Integration Requirements ).

Settlement processing#

Google Pay transactions follow the same Real Time or Deferred Settlement processing method configured on your merchant account (see Preparation for Integration ). If auto-settle is enabled, the authorise response returns autoSettle: true and no separate Settle call is required; otherwise call Settle once you are ready to fulfil the order.

Environment summary#

Security Considerations#

Essential security practices for both integration methods:

Merchant Decryption Flow (Advanced Security)#

• ✓ Implement proper key management for Google Pay decryption keys
• ✓ Ensure PCI DSS compliance when handling decrypted card data
• ✓ Validate token authenticity before processing

Gateway Decryption Flow (Standard Security)#

• ✓ Validate Google Pay response structure before forwarding
• ✓ Implement proper error handling for decryption failures
• ✓ Ensure secure transmission of encrypted tokens

Implementation Notes#

Key technical considerations for successful Google Pay integration:

Response Handling#

Both /card/google-pay/initiate and /card/initiate return the same initiate response structure. Fields with no value are omitted from the JSON.

{
  "transactionId": "48a94027-49bd-46f3-a761-7741a86ee944",
  "threeDSecureAuthRequired": false,
  "cvvRequired": false,
  "threeDSecureProvider": "NONE",
  "acsUrl": "",
  "acsPayload": "DEPRECATED",
  "acsMD": null,
  "profileUid": "5C4B9E2A-2C4F-4B4E-9E9F-2A6B0F1E7D11",
  "cardToken": "A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D",
  "transactionState": "INITIATED",
  "autoSettle": false,
  "retrievalReferenceNumber": "000000123456"
}

Authorise, Settle, Reverse and Refund responses are identical to the standard card responses documented in the Enterprise API .

Recommended Approach#

Gateway Decryption Flow — Recommended#

Best for most merchants

Benefits:

• ✓ Simpler implementation
• ✓ Reduced security responsibilities
• ✓ Faster time to market
• ✓ Lower maintenance overhead

Merchant Decryption Flow — Advanced Use Cases#

Choose only if you need:

• • Custom token validation logic
• • Integration with existing Google Pay infrastructure
• • Specific compliance or security requirements

Example Google Pay Request (Direct)#

const baseRequest = {
  apiVersion: 2,
  apiVersionMinor: 0
};

const allowedCardNetworks = ['VISA', 'MASTERCARD'];
const allowedAuthMethods = ['PAN_ONLY', 'CRYPTOGRAM_3DS'];

const baseCardPaymentMethod = {
  type: 'CARD',
  parameters: {
    allowedAuthMethods,
    allowedCardNetworks
  }
};

const directTokenizationSpecification = {
  type: 'DIRECT',
  parameters: {
    protocolVersion: 'ECv2',
    publicKey: 'YOUR_PUBLIC_KEY_HERE'
  }
};

const cardPaymentMethod = Object.assign(
  { tokenizationSpecification: directTokenizationSpecification },
  baseCardPaymentMethod
);

const paymentDataRequest = Object.assign({}, baseRequest, {
  allowedPaymentMethods: [cardPaymentMethod],
  transactionInfo: {
    totalPriceStatus: 'FINAL',
    totalPriceLabel: 'Total',
    totalPrice: '100.00',
    currencyCode: 'ZAR',
    countryCode: 'ZA',
    checkoutOption: 'DEFAULT'
  },
  merchantInfo: {
    merchantName: 'Example Merchant'
  }

});

Decrypting the Payment Token#

Google’s merchant cryptography guide documents the ECv2 token decryption process and recommends the Java Tink library for managing encrypted responses:

• How to decrypt the payment method token
• Use the Tink library to manage the encrypted response

Example Decrypted Token#

{
  "paymentMethod": "CARD",
  "paymentMethodDetails": {
    "authMethod": "CRYPTOGRAM_3DS",
    "pan": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2028,
    "cryptogram": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
    "eciIndicator": "05"
  },
  "messageId": "example-message-id",
  "messageExpiration": "1840752000000"
}