Google Pay™ Integration Guide

Table of Contents

• Getting Started
• Google Pay Policies & Terms
• Installation
• Quick Start
• Required Parameters
• Optional Parameters
• Tokenization & Gateway Configuration
• Supported Authentication Methods (allowedAuthMethods)
• 3D Secure for PAN_ONLY Credentials
• Supported Card Networks (allowedCardNetworks)
• Billing Address Parameters
• Shipping Address
• Handling the Payment Response
• Events
• Button Customization
• Complete Example
• Testing
• Going to Production
• Resources

🚀 Getting Started

Prerequisites

Before integrating Google Pay through the Ecart Pay SDK, ensure:

☝️ Google Pay Policies & Terms

All merchants using Google Pay through Ecart Pay must complete the following essential steps:

Comply with Google Policies

• Follow the Google Pay API Acceptable Use Policy.
• Accept the terms defined in the Google Pay API Terms of Service.
• Comply with the Google Pay Web Brand Guidelines.

📦 Installation

Add the Ecart Pay SDK <script> tag to your HTML page:

<!-- Production Environment -->
<script src="https://ecartpay.com/sdk/pay.js"></script>

<!-- Sandbox Environment (For testing purposes) -->
<script src="https://sandbox.ecartpay.com/sdk/pay.js"></script>

Note: Use the sandbox version for development and testing. Switch to the production script only when you're ready to go live.

The SDK automatically loads the Google Pay JavaScript client library when Pay.GooglePay.render() is called. No additional script tags are needed.

The SDK generates the IsReadyToPayRequest and PaymentDataRequest objects on your behalf using your Ecart Pay account configuration. You do not need to build these requests manually.

⚡ Quick Start

<div id="google-pay-button"></div>

<script src="https://ecartpay.com/sdk/pay.js"></script>
<script>
  // 1. Listen for events
  Pay.GooglePay.on('ready', function () {
    console.log('Google Pay button is ready');
  });

  Pay.GooglePay.on('success', function (event) {
    console.log('Payment successful:', event.detail);
    if (event.detail.redirect_url) {
      window.location.href = event.detail.redirect_url;
    }
  });

  Pay.GooglePay.on('error', function (event) {
    console.error('Error:', event.detail.message);
  });

  Pay.GooglePay.on('cancel', function () {
    console.log('Payment cancelled by user');
  });

  // 2. Render the button
  Pay.GooglePay.render({
    container: '#google-pay-button',
    orderId: 'YOUR_ORDER_ID',
    amount: 100.00,
    currency: 'MXN',
    countryCode: 'MX',
  });
</script>

📋 Required Parameters

🧩 Optional Parameters

💳 Tokenization & Gateway Configuration

As a supported Google Pay PSP, Ecart Pay uses the PAYMENT_GATEWAY tokenization type. The SDK configures this automatically.

When you integrate with Google Pay through the Ecart Pay SDK, the following values are set in the TokenizationSpecification object:

The SDK generates this configuration internally:

{
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "ecartpay",
      "gatewayMerchantId": "<Your Ecart Pay Account ID>"
    }
  }
}

Note: You do not need to set these values manually. The SDK retrieves them from Ecart Pay's configuration endpoint when render() is called.

🔐 Supported Authentication Methods (allowedAuthMethods)

The Ecart Pay integration with Google Pay supports two card authentication methods that merchants must define in the allowedAuthMethods property. These determine how the card credentials are provided:

Both methods are enabled by default. You can restrict to one if needed:

Pay.GooglePay.render({
  // ...
  allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
});

Important: If you only accept CRYPTOGRAM_3DS, the Google Pay button will not appear for users who don't have a device-tokenized card. We recommend enabling both methods for maximum compatibility.

🛡️ 3D Secure for PAN_ONLY Credentials

When a customer pays with a PAN_ONLY credential from Google Pay, Ecart Pay evaluates the transaction through its risk engine and may apply 3D Secure (3DS) step-up authentication to verify the cardholder's identity before processing the payment. This is required because PAN_ONLY returns the raw card PAN without device-level authentication.

How it works

1. The customer authorizes the payment on the Google Pay sheet.
2. Google Pay returns an encrypted PAN_ONLY payload containing the card number (PAN), expiration date, and billing information.
3. Ecart Pay decrypts the payload and runs the transaction through the risk evaluation engine.
4. The risk engine calculates a risk score based on configurable rules (see below).
5. Based on the risk score and your account's 3DS rules, Ecart Pay decides whether to trigger 3DS:
   • If 3DS is triggered, a step-up authentication challenge is initiated with the card issuer.
   • If 3DS is not required (low risk), the payment is processed directly.
6. If 3DS authentication is successful, Ecart Pay processes the payment with the acquiring gateway including the 3DS indicators (ECI, cryptogram).
7. If 3DS authentication fails, the payment is declined and the SDK emits an error event.
8. If the risk score is extremely high (highest level), the transaction is blocked automatically before reaching the gateway.

Risk evaluation engine

Before processing any PAN_ONLY payment, Ecart Pay evaluates the transaction against your account's risk rules. The engine analyzes the last 7 days of transaction history and assigns a cumulative risk score based on patterns such as:

Each rule has a configurable score weight. The total risk score determines the risk level:

When is 3DS triggered?

3DS is applied to a PAN_ONLY Google Pay transaction when any of the following conditions are met:

• The account's 3DS rule is set to "always" (3DS on every transaction).
• The transaction amount exceeds the threshold amount configured for the transaction currency.
• The risk score exceeds the 3DS risk threshold (default: 40).

For CRYPTOGRAM_3DS credentials

3DS is not applied to CRYPTOGRAM_3DS transactions because the device has already performed authentication via Google Pay. The cryptogram and ECI indicators from the device token are passed directly to the acquiring gateway.

Merchant configuration

No additional configuration is required by the merchant to enable 3DS for Google Pay. The risk rules and 3DS thresholds are managed through your Ecart Pay account settings. You can adjust risk rule weights and 3DS behavior from the Ecart Pay dashboard under Settings > Risk list.

For more details on how 3DS works in Ecart Pay, see the 3D Secure (3DS) Payment Flow documentation.

🌐 Supported Card Networks (allowedCardNetworks)

Merchants must define the card networks they accept using the allowedCardNetworks parameter. The Ecart Pay integration with Google Pay supports the following networks:

Default: ['VISA', 'MASTERCARD', 'AMEX']

Note: Only VISA, MASTERCARD, and AMEX are currently supported by Ecart Pay. Do not include unsupported networks in allowedCardNetworks as transactions with those cards will not be processed.

Pay.GooglePay.render({
  // ...
  allowedCardNetworks: ['VISA', 'MASTERCARD', 'AMEX'],
});

Note: Only define the networks that your Ecart Pay account supports. Contact Ecart Pay support if you need to enable additional networks. Refer to the Google Pay Web Developer Documentation for the full list of supported values.

🏠 Billing Address Parameters

If your payment flow requires a billing address for verification (e.g., AVS checks), you must enable it in the Google Pay configuration using billingAddressRequired and billingAddressParameters.

Configuration

Example

Pay.GooglePay.render({
  // ...
  billingAddressRequired: true,
  billingAddressParameters: {
    format: 'FULL',
    phoneNumberRequired: true,
  },
});

This generates the following structure in the Google Pay API request:

{
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "billingAddressRequired": true,
        "billingAddressParameters": {
          "format": "FULL",
          "phoneNumberRequired": true
        },
        "allowedCardNetworks": ["VISA", "MASTERCARD", "AMEX"],
        "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"]
      },
      "tokenizationSpecification": {
        "type": "PAYMENT_GATEWAY",
        "parameters": {
          "gateway": "ecartpay",
          "gatewayMerchantId": "<Your Ecart Pay Account ID>"
        }
      }
    }
  ]
}

For the full specification, see BillingAddressParameters in the Google Pay documentation.

📦 Shipping Address

To request a shipping address from the Google Pay payment sheet:

Pay.GooglePay.render({
  // ...
  shippingAddressRequired: true,
  shippingAddressParameters: {
    allowedCountryCodes: ['MX', 'US', 'CA'],
    phoneNumberRequired: true,
  },
});

💸 Handling the Payment Response

The SDK handles the entire payment flow. You only need to listen for events.

Payment Data Flow

Pay.GooglePay.on('success', function (event) {
  var result = event.detail;
  console.log('Payment status:', result.status);
  if (result.redirect_url) {
    window.location.href = result.redirect_url;
  }
});

Best Practice: Always use the order status from the Orders API (GET /api/orders/:id) as the source of truth for your business logic. Do not rely solely on the SDK event.

📡 Events

Pay.GooglePay.on('ready', function () { /* button is visible */ });
Pay.GooglePay.on('unavailable', function (e) { /* hide section */ });
Pay.GooglePay.on('success', function (e) { /* redirect */ });
Pay.GooglePay.on('error', function (e) { /* show error */ });
Pay.GooglePay.on('cancel', function () { /* user closed */ });

🎨 Button Customization

The SDK uses the official Google Pay createButton() method, which renders a fully compliant button that:

• Personalized — displays the user's saved card info when available
• Localized — automatically translates to the user's browser language
• Compliant — always uses official Google Pay assets

Pay.GooglePay.render({
  // ...
  buttonColor: 'black',
  buttonType: 'pay',
  buttonSizeMode: 'fill',
  buttonLocale: 'es',
  buttonRadius: 8,
});

Important: Do not create your own Google Pay buttons or alter the official assets. Always use the button rendered by the SDK, in compliance with the Google Pay Web Brand Guidelines.

🧪 Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Google Pay Checkout - Ecart Pay</title>
    <style>
        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; }
        .checkout { max-width: 480px; margin: 40px auto; padding: 24px; background: #fff; border-radius: 12px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
        #gpay-container { min-height: 48px; margin: 16px 0; }
        .status { padding: 12px; border-radius: 8px; margin-top: 12px; display: none; font-size: 14px; }
        .status.success { display: block; background: #d1fae5; color: #065f46; }
        .status.error { display: block; background: #fee2e2; color: #991b1b; }
    </style>
</head>
<body>
    <div class="checkout">
        <h2>Checkout</h2>
        <p>Total: <strong>$100.00 MXN</strong></p>
        <div id="gpay-container"></div>
        <div id="status" class="status"></div>
    </div>

    <script src="https://ecartpay.com/sdk/pay.js"></script>
    <script>
        var statusEl = document.getElementById('status');

        Pay.GooglePay.on('success', function (event) {
            statusEl.className = 'status success';
            statusEl.textContent = 'Payment successful!';
            if (event.detail.redirect_url) {
                window.location.href = event.detail.redirect_url;
            }
        });

        Pay.GooglePay.on('error', function (event) {
            statusEl.className = 'status error';
            statusEl.textContent = 'Error: ' + event.detail.message;
        });

        Pay.GooglePay.on('cancel', function () {
            statusEl.className = 'status error';
            statusEl.textContent = 'Payment cancelled.';
        });

        // Replace YOUR_ORDER_ID with a real order ID from the Ecart Pay Orders API
        Pay.GooglePay.render({
            container: '#gpay-container',
            orderId: 'YOUR_ORDER_ID',
            amount: 100.00,
            currency: 'MXN',
            countryCode: 'MX',
            buttonColor: 'black',
            buttonType: 'pay',
            buttonLocale: 'es',
            buttonRadius: 4,
            allowedCardNetworks: ['VISA', 'MASTERCARD', 'AMEX'],
            allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
            billingAddressRequired: true,
            billingAddressParameters: {
                format: 'MIN',
                phoneNumberRequired: true,
            },
        });
    </script>
</body>
</html>

Note: You can copy and paste this into an .html file and run it locally to test a full Google Pay checkout flow. Remember to use the sandbox SDK for testing.

🧪 Testing

Use the Sandbox environment for testing:

<script src="https://sandbox.ecartpay.com/sdk/pay.js"></script>

In sandbox mode, the Google Pay button operates in TEST environment, allowing testing with the Google Pay Test Card Suite without processing real payments.

🚀 Going to Production

Before going live with Google Pay, merchants must complete the following steps:

Note: As a Payment Service Provider (PSP), Ecart Pay is already registered with Google Pay and manages the production access on behalf of all merchants. You do not need to register your business separately in the Google Pay & Wallet Console or obtain your own merchantId. Ecart Pay's gateway registration with Google covers all merchants using the Ecart Pay SDK.

However, if you want to display your own business name on the Google Pay payment sheet, or if you process more than 50 domains, you may optionally register in the Google Pay & Wallet Console and provide your merchantId to Ecart Pay support to configure it for your account.

🔎 Resources

Google Pay Documentation

Ecart Pay Documentation