Google Pay™ Integration Guide

Accept payments with Google Pay using the Ecart Pay SDK. As a supported Payment Service Provider (PSP), Ecart Pay handles token decryption, 3D Secure verification, and payment processing — your integration is just a few lines of JavaScript.

Each merchant that serves the Google Pay button from its own domain sends its own Google Pay merchant ID. See Going to Production.

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
• Troubleshooting: "Domain is not valid"
• 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, the SDK automatically opens a secure modal on your page where the issuer's step-up authentication challenge is presented. The customer never leaves your site.
   • If 3DS is not required (low risk), the payment is processed directly with no challenge.
6. Once the challenge is completed, the SDK finalizes the payment inside the modal and closes it.
7. If 3DS authentication is successful, Ecart Pay processes the payment with the acquiring gateway including the 3DS indicators (ECI, cryptogram) and the SDK emits a success event with the redirect_url.
8. If 3DS authentication fails, the payment is declined, the modal is closed and the SDK emits an error event.
9. If the risk score is extremely high (highest level), the transaction is blocked automatically before reaching the gateway.

UX: everything happens in the SDK

The entire 3DS challenge is handled by the SDK inside a modal overlay rendered on top of your checkout — there is no full-page redirect to complete authentication. You only listen for the success/error events; the SDK manages opening the modal, running the challenge, finalizing the payment and closing the modal.

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 or code is required by the merchant to enable 3DS for Google Pay. 3DS is not a separate module you integrate — it is built into the Pay.GooglePay flow and triggered automatically when needed. 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 */ });

When the error comes from Google Pay itself, statusCode and statusMessage contain Google's own diagnostic (for example DEVELOPER_ERROR and the reason the request was rejected). message falls back to statusMessage so it is always human readable. Log both while integrating. See Troubleshooting.

🎨 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',
            // Required in production when the button is served from your own domain.
            // merchantId: 'BCR2DN...',
            // merchantName: 'Your Business',
            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:

Pay.GooglePay.render({
  container: '#google-pay-button',
  orderId: 'YOUR_ORDER_ID',
  amount: 100.00,
  currency: 'MXN',
  countryCode: 'MX',
  merchantId: 'BCR2DN...',      // your Google Pay merchant ID (production)
  merchantName: 'Your Business', // shown on the payment sheet
});

Important: Ecart Pay is registered with Google as the gateway (ecartpay), which lets Google route the encrypted token to us. It does not authorize your website. In production, Google checks that the domain calling Google Pay is registered to the merchantId sent in the request. Ecart Pay's own merchant ID is only associated with Ecart Pay's domains, so if you serve the button from your own domain you must register your own merchant ID and domain and send it in render(). Without it, Google rejects the payment with a "domain is not valid" error.

The SDK only sends merchantId in the production environment. In sandbox (TEST) Google does not validate domains, so the button can work there and still fail in production if the merchant ID is missing. See the Google Pay Productive Merchant Approval Guide for the step-by-step process.

🩺 Troubleshooting: "Domain is not valid"

Listen to the error event and log event.detail.statusCode and event.detail.statusMessage to see exactly what Google rejected.

🔎 Resources

Google Pay Documentation

Ecart Pay Documentation

Google Pay is a trademark of Google LLC.