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.
• 3DS verification: Authentication is performed by Google Pay™. Note: If the issuer or risk management requires additional 3DS verification, SUNBAY does not currently support this flow. Such transactions will be treated as high-risk and directly declined (transactionStatus = F).
• 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), Google Pay is available by default; SUNBAY owns the wallet UI. Follow the standard Hosted Payment Page flow.

By integrating your hosted checkout solution with Google Pay, you make it easier to offer Google Pay as a payment option to your customers.

Steps (summary)

1. Backend calls Create checkout session and receives checkoutUrl (see Hosted Payment Page requirements in online docs).
2. Redirect the browser to checkoutUrl; customer picks Google Pay and authorizes.
3. Handle merchantReturnUrl return and notifyUrl Webhook per Hosted Payment Page guidance.

Full field and flow details:

• Hosted Payment Page

Additional requirements for hosted checkout

When using the hosted checkout, SUNBAY handles the Google Pay front-end integration on your behalf, including:

• Loading the Google Pay API JavaScript client library
• Generating IsReadyToPayRequest and PaymentDataRequest properties
• Handling Google Pay button display and interaction
• Adhering to Google Pay brand guidelines
• Automatically configuring CRYPTOGRAM_3DS auth method

You only need to ensure:

1. Enable Google Pay functionality in BizHub
2. Set supported card networks

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.

Flow

Integration steps

1) 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 

<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 (including declined high-risk transactions)
    // 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

Response handling:

• transactionStatus = S: Payment successful
• transactionStatus = F: Payment failed (including declined high-risk transactions)
• 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
• Note: SUNBAY does not currently support additional 3DS verification flows. Transactions requiring additional 3DS will be directly declined
• 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