Google Pay™ Integration

Executive Summary

1. Merchants use Google Pay JavaScript to obtain an encrypted payment token (tokenizationData.token).
2. The merchant forwards the raw token string to RapidCents via our server-to-server API.
3. RapidCents decrypts and validates the token server-side (Java Tink), applies risk controls (including risk-based 3DS step-up), and submits the transaction to Visa, Mastercard, Discover, Amex.

What Google Reviews (at a Glance)

This documentation covers the items typically reviewed in the Google Pay go-live checklist:

• Tokenization parameters used in tokenizationSpecification (gateway, gatewayMerchantId)
• Payment token handling — raw token forwarding, no client re-serialization
• Decryption & validation — server-side, using Google Pay ECv2 + Java Tink
• Transaction processing path — submission to Visa, Mastercard, Discover, Amex
• 3D Secure handling — risk-based step-up applied to PAN_ONLY
• Environment separation — TEST vs PRODUCTION keys and tooling
• Security & compliance — PCI DSS-compliant handling of sensitive payment data

Required Acknowledgement: PAN_ONLY and 3D Secure

In practice:

• We detect the token's authMethod (CRYPTOGRAM_3DS or PAN_ONLY).
• For PAN_ONLY, we apply the same risk-based decisioning used for non-Google Pay card transactions.
• When step-up is required, we trigger our standard 3DS flow (where the merchant channel supports it) or return an appropriate decline/soft-decline result if step-up cannot be completed in the current context.

Terminology

Decrypted Payload Fields (Server-Side — RapidCents Internal)

After decrypting the ECv2 payload, RapidCents processes the following fields to authorize the transaction:

This information is provided for transparency and completeness. The merchant’s integration does not require knowledge of these fields — simply forward the encrypted token as described in Token Handling.

End-to-End Integration Flow

1. The merchant’s frontend uses the Google Pay JavaScript API (paymentsClient.loadPaymentData()) to present the Google Pay™ payment sheet to the customer.
2. After the customer authorizes payment, Google Pay returns an encrypted ECv2 token (paymentMethodData.tokenizationData.token) to the merchant’s frontend.
3. The merchant’s server forwards the raw token string (without parsing or re-serializing) to the RapidCents server-to-server API along with the amount, currency, and order details.
4. RapidCents verifies the token signature and decrypts the ECv2 payload using Java Tink.
5. RapidCents applies risk controls. For PAN_ONLY, 3DS step-up logic is triggered if needed.
6. RapidCents submits the transaction (with DSRP cryptogram if present) to Visa, Mastercard, Discover, Amex.
7. RapidCents returns the transaction result (approved/declined) back to the merchant.

Encryption / Decryption Responsibilities

Merchant Integration (Google Pay™ API for Web)

Merchants should implement Google Pay™ Web per Google's official documentation:

Required Google Resources

• Google Pay API for Web — Developer Documentation
• Payment Data Cryptography
• Google Pay Web Brand Guidelines — required for button rendering, logo usage, and brand compliance
• Google Pay Web Integration Checklist — complete all items before requesting production access
• Publish Your Integration — submit your integration for Google review to obtain production access

Android Integration

If your application also supports Android, you must additionally follow the Android-specific documentation:

• Google Pay API for Android — Developer Documentation
• Google Pay Android Brand Guidelines
• Google Pay Android Integration Checklist

Compliance Requirements

By using Google Pay™ through RapidCents, the merchant agrees to:

• Use Google Pay™ only for lawful transactions in compliance with all applicable laws and regulations.
• Display the Google Pay™ button and branding in accordance with the Google Pay Brand Guidelines.
• Not store, log, or transmit decrypted card data outside of PCI DSS-compliant systems.
• Complete the Integration Checklist and publish the integration before going live.

PaymentDataRequest Example

const paymentDataRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [
    {
      type: "CARD",
      parameters: {
        allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        allowedCardNetworks: ["VISA", "MASTERCARD", "AMEX", "DISCOVER"],
      },
      tokenizationSpecification: {
        type: "PAYMENT_GATEWAY",
        parameters: {
          gateway: "rapidcentspay",
          gatewayMerchantId: "googletest",
        },
      },
    },
  ],
  merchantInfo: {
    merchantName: "Acme Corp",  // REQUIRED — enter your own business name
  },
  transactionInfo: {
    totalPriceStatus: "FINAL",
    totalPrice: "10.00",
    currencyCode: "CAD",
  },
};

Billing Address Configuration

If your integration requires the customer's billing address for verification (AVS) or compliance purposes, add the billingAddressRequired parameter to allowedPaymentMethods[].parameters:

parameters: {
  allowedAuthMethods: ["PAN_ONLY", "CRYPTOGRAM_3DS"],
  allowedCardNetworks: ["VISA", "MASTERCARD", "AMEX", "DISCOVER"],
  billingAddressRequired: true,
  billingAddressParameters: {
    format: "FULL",  // "MIN" for postal code + country only
    phoneNumberRequired: false,
  },
}

After paymentsClient.loadPaymentData(paymentDataRequest), use:

• paymentData.paymentMethodData.tokenizationData.token (string)

Critical Token Handling Requirements

RapidCents Server-to-Server API

RapidCents provides Google Pay processing endpoints:

Request Example

POST /api/google-pay/payment/process
Content-Type: application/json
Accept: application/json

{
  "payment_token": "{\"signature\":\"...\",\"intermediateSigningKey\":{...},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"...\"}",
  "merchant_id": "gateway:rapidcentspay",
  "amount": 10.00,
  "currency": "CAD",
  "order_id": "ORDER-12345",
  "merchant_reference": "optional-reference"
}

Response Example

{
  "success": true,
  "transaction_result": {
    "status": "Approved",
    "auth_code": "123456"
  }
}

Environments and Key Management

RapidCents uses strictly separated TEST and PRODUCTION key material internally:

Merchant Configuration

Merchants only need the following parameters in their tokenizationSpecification — no key management is required:

Testing and Diagnostics

Optional status and testing endpoints (access may be restricted per deployment):

Troubleshooting

Security and Compliance

• All requests must use HTTPS.
• Treat tokens and decrypted payment data as sensitive and handle per PCI DSS requirements.
• Do not persist decrypted PAN/cryptogram unless required and compliant.
• Keep key material in a secret manager and rotate if needed.

Support

For integration assistance, please provide:

• Merchant name and MID / identifier
• Environment (TEST vs PRODUCTION)
• Approximate timestamps and request IDs