Google Pay™ integration

With Google Pay™, customers can pay quickly using cards stored in their Google account without re-entering card details. Google stores card data securely and works across phones, desktops, OSes, and major browsers.

Basics (all paths)

The following applies whether you use the Hosted Payment Page or API Only. Read this section before choosing a path.

Supported platforms

SUNBAY currently supports Web integration only. You can define supported card networks in the allowedCardNetworks property. For details, see Google Pay Web Developer Documentation .

Supported card brands

• AMEX (American Express)
• DISCOVER
• JCB
• MASTERCARD
• VISA

Supported auth method

SUNBAY currently supports CRYPTOGRAM_3DS auth method only:

• Description: Tokenized virtual card stored on the device. Google Pay returns an encrypted cryptogram suitable for 3DS-capable processing.
• Supported countries: Global (based on your merchant configuration)
• PCI DSS requirement: Lower, as it doesn’t involve plaintext PAN

Billing address verification (AVS)

SUNBAY enables AVS by default and may request billing address from the Google Pay API for the transaction.

If Google Pay requires a billing address, ensure you add the required parameters. For details, see BillingAddressParameters .

Billing address request example:

"allowedPaymentMethods": [{
  "type": "CARD",
  "parameters": {
    "billingAddressRequired": true,
    "billingAddressParameters": {
      "phoneNumberRequired": true,
      "format": "MIN"
    },
    "allowedCardNetworks": ["VISA", "MASTERCARD", "AMEX"],
    "allowedAuthMethods": ["CRYPTOGRAM_3DS"]
  },
  "tokenizationSpecification": {...}
}]

Two integration paths

Pick based on how much payment UI you want to own (details and sample code below).

Hosted Payment Page

On the SUNBAY Hosted Payment Page (HPP), SUNBAY owns the Google Pay wallet UI. Google Pay is displayed only after the Partner enables a Google Pay-capable payment channel for the merchant in SUNBAY Copilot, and when Google Pay is available to the customer.

Integration steps

SUNBAY handles Google Pay front-end functionality on the Hosted Payment Page, so the Partner or merchant does not need to develop it.

1. Sign in to SUNBAY Copilot with your Partner account and enable a payment channel that supports Google Pay for the merchant.
2. After the channel configuration is active, the merchant backend calls Create checkout session and receives checkoutUrl.
3. Redirect the browser to checkoutUrl, then verify on an eligible device and browser that the customer can select Google Pay and authorize.
4. Handle the merchantReturnUrl return and notifyUrl Webhook according to the Hosted Payment Page guidance.

For complete session fields, redirect behavior, and result handling, see:

• Hosted Payment Page

API Only integration

Use this when you already have a checkout page: integrate Google Pay JS, obtain the payment token, and call SUNBAY direct payment—no hosted SUNBAY checkout page.

Prerequisites

Before writing front-end code:

1. Sign in to the Google Pay & Wallet Console  with the Google account that manages your business.
2. Create or complete the Google Pay merchant profile.
3. Complete the required business information and website verification, then apply for Google Pay API production access.
4. After Google approves the profile, copy the Google Pay merchant ID from the console.

Use the Google Pay merchant ID as merchantInfo.merchantId:

const googleMerchantId = 'YOUR_GOOGLE_MERCHANT_ID';
 
const merchantInfo = {
  merchantId: googleMerchantId,
  merchantName: 'Your Store',
};

Flow

Integration steps

1) Configure tokenizationSpecification (gateway)

As a payment service provider supported by the Google Pay API, SUNBAY’s integration allows you (the merchant) to use the Google Pay API’s PAYMENT_GATEWAY integration type, and we handle all decryption on your behalf.

When you integrate with the Google Pay API as a merchant, be sure to set the following values in the TokenizationSpecification object:

• gateway: Set this value to sunbay (this is the gateway ID value SUNBAY set during technical onboarding with Google)
• gatewayMerchantId: Set this value to your SUNBAY merchant ID (consistent with the merchant ID in BizHub)

Here’s an API configuration example:

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    gateway: 'sunbay',
    gatewayMerchantId: 'YOUR_SUNBAY_MERCHANT_ID', // Your merchant ID in SUNBAY system
  },
};

Complete the rest per Google’s tutorial (PaymentsClient, PaymentDataRequest, isReadyToPay, button, merchantInfo , transactionInfo , etc.):

• Google Pay Web Developer Documentation 
• Google Pay Web Integration Tutorial 
• Google Pay Web Integration Checklist 

2) Load the Google Pay JS SDK

Load the official Google Pay JS SDK and initialize your integration after the script is ready:

<div id="gpay-container"></div>
 
<script async
  src="https://pay.google.com/gp/p/js/pay.js"
  onload="onGooglePayLoaded()">
</script>

3) Initialize and render the button

After general setup from the tutorial, attach the gateway tokenizationSpecification to the card payment method. Minimal end-to-end sample (networks/environment still follow Google’s guide):

const environment = 'TEST'; // use PRODUCTION in live
const paymentsClient = new google.payments.api.PaymentsClient({ environment });
 
const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    gateway: 'sunbay',
    gatewayMerchantId: 'YOUR_SUNBAY_MERCHANT_ID',
  },
};
 
const allowedCardNetworks = ['AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA'];
const allowedAuthMethods = ['CRYPTOGRAM_3DS'];
const googleMerchantId = 'YOUR_GOOGLE_MERCHANT_ID';
const merchantName = 'Your Store';
 
function getPaymentDataRequest(orderAmount, currencyCode) {
  return {
    apiVersion: 2,
    apiVersionMinor: 0,
    allowedPaymentMethods: [{
      type: 'CARD',
      parameters: {
        allowedAuthMethods: allowedAuthMethods,
        allowedCardNetworks: allowedCardNetworks,
      },
      tokenizationSpecification,
    }],
    transactionInfo: {
      countryCode: 'US',
      currencyCode: currencyCode,
      totalPriceStatus: 'FINAL',
      totalPrice: orderAmount,
    },
    merchantInfo: {
      merchantId: googleMerchantId,
      merchantName: merchantName,
    },
  };
}
 
function onGooglePayLoaded() {
  const baseCardMethod = {
    type: 'CARD',
    parameters: {
      allowedAuthMethods: allowedAuthMethods,
      allowedCardNetworks: allowedCardNetworks,
    },
  };
  const isReadyToPayRequest = {
    apiVersion: 2,
    apiVersionMinor: 0,
    allowedPaymentMethods: [baseCardMethod],
  };
 
  paymentsClient.isReadyToPay(isReadyToPayRequest).then(response => {
    if (response.result) {
      const button = paymentsClient.createButton({
        onClick: onGooglePayButtonClicked,
        allowedPaymentMethods: [baseCardMethod],
      });
      document.getElementById('gpay-container').appendChild(button);
    }
  });
}
 
function onGooglePayButtonClicked() {
  const request = getPaymentDataRequest('99.99', 'USD');
  paymentsClient.loadPaymentData(request)
    .then(paymentData => {
      const token = paymentData.paymentMethodData.tokenizationData.token;
      submitTokenToBackend(token);
    })
    .catch(err => console.error('User cancelled or payment failed', err));
}

4) Process Google Pay payload

When a customer pays with Google Pay, Google Pay generates encrypted data containing payment information. The encrypted data can be extracted from the paymentMethodData.tokenizationData.token property of the PaymentData response object.

After obtaining the Google Pay encrypted payment token, send it to your backend:

async function submitTokenToBackend(token) {
  const body = await fetch('{YOUR_BACKEND_ENDPOINT}', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token, referenceOrderId: 'ORDER_20240101_001' }),
  }).then(res => res.json());
 
  const data = body.data ?? body;
  if (data.transactionStatus === 'S') {
    // success — navigate to result page
  } else if (data.transactionStatus === 'F') {
    // payment failed
    // display error message to user
  }
}

5) Backend calls SUNBAY

Your backend sends the Google-encrypted payment data and transaction data to the SUNBAY server, calling the Direct payment endpoint to complete the charge:

curl --request POST \
  --url https://{API_DOMAIN}/v1/checkout/sale \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "appId": "smgq9m496ty14ouw",
    "merchantId": "M1260231004",
    "transactionRequestId": "sale_req_1741680000000",
    "referenceOrderId": "ORDER_20260311_001",
    "description": "iPhone 16 Pro purchase",
    "amount": {
      "orderAmount": 99999,
      "taxAmount": 8000,
      "priceCurrency": "USD"
    },
    "paymentMethod": "GOOGLE_PAY",
    "cardEncryptedData": "<Google Pay token JSON string>",
    "notifyUrl": "https://merchant.example.com/webhook/payment"
  }'

Key parameter descriptions:

• paymentMethod: Set to GOOGLE_PAY
• cardEncryptedData: Google Pay encrypted token extracted from paymentMethodData.tokenizationData.token (JSON string format)
• notifyUrl: Webhook URL for receiving asynchronous payment result notifications

Example cardEncryptedData value

paymentMethodData.tokenizationData.token returned by Google Pay is itself a JSON string; pass it through as-is (do not decode, reformat, or modify it) as the cardEncryptedData value:

{
  "signature": "MEYCIQC2suBfbM2KQ0pyHbpQeSdTW+5IibU5pMYJWObxzktVSgIhANduHxGgvgnIzK9pSy92AxoMnqyduaq1MJssO45snr5s",
  "intermediateSigningKey": {
    "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEv7guHGeoGrJcE8Ck4eUvHlaAHEpXyi1wOlwoyeZDcZjxqIJQg8ALI2vxgTPz2Uj9AB+wjtts4cwVurImVla6hg==\",\"keyExpiration\":\"1773378525666\"}",
    "signatures": [
      "MEYCIQCFlRwh2+JSlmI3FrU/NptCk3lqXToLQ3+9YchfxaOGugIhAIKki3B3ZSlWJofO+qwsrtipyJLWOOxrzlQZWFPzTGDa"
    ]
  },
  "protocolVersion": "ECv2",
  "signedMessage": "{\"encryptedMessage\":\"b9uJw1e3J+Xff86rWM8AeGvjnnDq7grHOMapz6yNKrjVZKOgzZuXMtE6MJD5YPHvNgRxA3an0bux9K3so1IY33A0Lqke3kTsou6LmUpIm6TGzO+Wpw/cwheKFjlBckBtKqOdvk38vvrQQTEHumhxfQ/UdyBghjgMfAL2S3e624U2BF370s1QW7nMZ4kHxEbmVDqCgyg22OvZmSpYRp5zGgBh0RYxxTnPb9Ph6GnYBNVbDHkCc6Haxzf955m6PY9FRSKiDun8XER4fvJcGzyHFgfha1Wb07dccZNCR9AhLZVPcxDjnlVGymtciKT85EtYRzO3lFdvPnOZhdFs38NeS9a2Zp4T3H5J5KDU32DxsSXalzQw5na/CTxFTNJ9w4BNd9JouOh4Cy62rwTH+Gcud1ugu1R1A2eCyXKAgOuEENyJ8BFqODtyKNEkmoyCf9R2H652/Q8dnJCAWJq2reLl6Ha9NH3VMjD6Z7PkA9ERGAFGtkQ0ReRFemwThrON1U0pbf5t4ouQV2AjQ+SSDigNTl6KiUlagAPpwgcqs9QbxDDCTmSxdv6Dx08XdKdsJLZ9MSy4erizpFWoL31BMYzs8prHYC6/AdV7DNEB6CXTmw==\",\"ephemeralPublicKey\":\"BHmBgqiz3thbRGWPXayIO65dnljo+2EKNJNly4DAiS7bz2rx3MMMnSv386v0tioEjcR4XOFBcltqlVPKXoLbYKw=\",\"tag\":\"/zIW7rohnjAB797YeS7U0LulVqJP/dOECHnzx9+4fCo=\"}"
}

Response handling:

• transactionStatus = S: Payment successful
• transactionStatus = F: Payment failed
• For other statuses and Webhook handling, see API Only

Field reference: Direct payment API.

Google Pay™ security & compliance

• Do not log or store Google Pay tokens in the browser
• Decrypt or transform tokens only on the server
• Google Pay requires HTTPS (no HTTP pages)
• User data returned by Google Pay (e.g. billing address) is for this transaction only
• Use the data received from the Google Pay API only to process transactions—all other use cases require separate, express consent from the user
• Ensure your existing risk checks and controls for card transactions are also applied to Google Pay transactions
• Broader HTTPS, key, and Webhook signing practices: API Only

Google Pay™ branding requirements

When integrating Google Pay, you must adhere to the brand guidelines :

• Use only Google Pay buttons and marks provided by Google—do not create custom buttons or alter colors, fonts, or padding
• Use the createButton() JavaScript method to ensure brand compliance and automatic updates
• Choose button style (dark/light) based on background—dark buttons on light backgrounds, light buttons on dark/colorful backgrounds
• Maintain minimum clear space of 8dp on all sides of the button
• Display Google Pay with equal prominence to other payment methods
• Always write “Google Pay” in English—do not translate or abbreviate
• Capitalize only the “G” and “P” (not “GOOGLE PAY” unless matching your site’s typographic style)
• Show the Google Pay button only after confirming the user’s ability to pay via isReadyToPay()
• On confirmation pages and receipts, indicate payment was made with Google Pay (e.g., “Network •••• 1234 with Google Pay”)

Testing your integration

Before going live, test your integration in the TEST environment:

1. Initialize PaymentsClient with environment: 'TEST' to receive test payment data (not live/chargeable)
2. Test on the latest version of supported browsers (Chrome, Firefox, Safari, Edge, Opera, UC Browser)
3. Use browser developer console to view errors and warnings from the Google Pay API
4. For CRYPTOGRAM_3DS, test with an eligible card added to Google Pay on Android devices
5. Test address parsing with varied formats (different name structures, multiple address lines)
6. Verify loadPaymentData() is called synchronously on button click to avoid popup blockers
7. Test shipping restrictions if applicable
8. Test both successful and failed payment scenarios, ensuring proper handling of transactionStatus

References