BoxPay Payments

⌘K
  2. Home
  4. Docs
  6. BoxPay Payments
  8. Google Pay Integration Guide

Google Pay Integration Guide

1. Overview

Google Pay™ lets your customers pay quickly and securely using the cards saved to their Google Account. BoxPay offers Google Pay through its hosted checkout: the Google Pay button is presented directly on the BoxPay-hosted checkout page, and BoxPay handles the entire Google Pay interaction and payment processing, routing the transaction to any connected acquirer/PSP (e.g. Trust Payments, Revolut, Adyen). You do not need to integrate the Google Pay API, host the Google Pay button, or handle Google Pay payment data on your own website — you simply enable Google Pay for your BoxPay account and direct shoppers to the hosted checkout.

2. Before You Begin

If this is your first payment method, make sure to follow the Getting Started guide to begin processing payments with BoxPay.

All merchants must adhere to the Google Pay and Wallet APIs Acceptable Use Policy (https://payments.developers.google.com/terms/aup) and accept the terms defined in the Google Pay API Terms of Service (https://payments.developers.google.com/terms/sellertos).

If you provide Google Pay as a payment method to your customers and reference it anywhere on your own website or marketing materials, you must use the official Google Pay logo and button assets in compliance with the Google Pay Web Brand Guidelines, without modifications to the Google Pay asset colors, proportions, or appearance.

3. Prerequisites

  • An active BoxPay merchant account with API credentials (see Getting Started).
  • At least one PSP connected to your BoxPay merchant account that supports the Google Pay wallet.
  • Your website integrated with BoxPay’s hosted checkout. No Google Pay client-side integration, Google Pay API credentials, or Google account setup is required on your side — BoxPay renders and operates the Google Pay button on the hosted checkout page.

4. Integration Flow

Merchant server creates a checkout session via BoxPay API
  ->  Shopper is directed to the BoxPay-hosted checkout page
  ->  Shopper selects Google Pay and approves payment in the Google Pay sheet
  ->  BoxPay processes the payment and routes it to the connected PSP
  ->  BoxPay returns a unified Approved / RequiresAction / Rejected result

The Google Pay button, the Google Pay payment sheet, and all Google Pay payment data handling take place on BoxPay’s hosted checkout page. Your integration is limited to creating the checkout session and consuming the result — no Google Pay-specific code is required on your website.

5. Enabling Google Pay in the BoxPay Dashboard

Google Pay is enabled per merchant account through the BoxPay Dashboard. Once enabled, Google Pay appears automatically as a payment option on the BoxPay-hosted checkout page for eligible shoppers.

  1. Log in to your BoxPay Dashboard and open Configurations from the left-hand menu.
  2. Click Add Payment Gateway in the top-right corner.
  3. Under the Payment Gateways tab, choose a gateway that supports the Wallet category and click + Add (see Supported Payment Service Providers and Payment Methods for the current list of gateways supporting Google Pay — for example, Trust).
  4. Complete the configuration for that gateway (credentials, environment, etc.) and save.
  5. Switch to the Payment Options tab, open Wallets, and enable the toggle for Google Pay.
  6. Adhere to Google policies: all merchants are required to follow the Google Pay and Wallet APIs Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.
  7. Create a checkout session as normal and direct the shopper to the hosted checkout page — Google Pay will be presented to eligible shoppers automatically. See Create a Checkout Session for the full hosted checkout integration steps.

6. Going Live

Because Google Pay is offered through BoxPay’s hosted checkout, production access to the Google Pay API is managed by BoxPay at the platform level. You do not need to individually register with Google, request production access, or allowlist your domains in the Google Pay & Wallet Console.

To go live with Google Pay, complete the following on your BoxPay account:

  1. Complete BoxPay merchant onboarding and switch your account to the Live environment.
  2. Configure your Google Pay-supporting gateway with live credentials and enable the Google Pay wallet toggle in the Live environment (Section 5).
  3. Perform a test transaction on your live hosted checkout to confirm Google Pay is presented and processing correctly.

7. Checkout Session Parameters for Google Pay

Google Pay relies on the following parameters when creating a checkout session (see Create a Checkout Session for the full API reference):

ParameterRequiredDescription
order.countryCodeYesThe merchant’s country (ISO 3166-1 alpha-2) — where the transaction is processed, not the buyer’s country.
shopperAuthentication.threeDSAuthenticationNoMerchant’s 3DS preference for PAN-only transactions: Yes / Prefer / No. If omitted, defaults to Yes.

order.countryCode maps to Google Pay’s TransactionInfo.countryCode: the ISO 3166-1 alpha-2 country code where the transaction is processed. Use the country of your acquiring entity — for example, if your acquirer is in the EEA, this is required for SCA compliance.

8. Authentication & Step-Up Behaviour

Google Pay returns one of two authentication methods, and BoxPay applies a consistent, predictable rule based on that method:

Google Pay auth methodBoxPay behaviour
CRYPTOGRAM_3DS — tokenized card stored on the shopper’s device, authenticated by Google PayTreated as already authenticated by Google Pay; no additional 3DS is required. Submitted to the PSP as a single authorization request.
PAN_ONLY — physical card details stored in the shopper’s Google Account, not authenticated by Google PayRouted through the connected PSP’s 3DS2 flow according to your threeDSAuthentication setting (Section 7).

For PAN_ONLY transactions, the threeDSAuthentication setting determines the PSP’s step-up behaviour:

SettingBehaviour
NoDirect authorization; no 3DS step-up is invoked.
Yes (default)Full 3DS2 authentication is required. Authorization proceeds only where liability shift is achieved; otherwise the transaction is declined.
Prefer3DS2 is attempted first, with a controlled fallback to a non-3DS authorization if authentication cannot be completed.

If the threeDSAuthentication field is not sent in the checkout session request, BoxPay defaults to Yes, meaning full 3DS2 authentication is enabled for PAN_ONLY transactions unless you explicitly opt out.

Where a challenge is required, the shopper completes it as part of the hosted checkout flow — BoxPay manages the issuer redirect and challenge handling. This applies uniformly across all connected PSPs.

9. Supported PSPs

Google Pay processes through any PSP connected to your BoxPay account that supports the Wallet category — see Supported Payment Service Providers and Payment Methods for the current list. The authentication and step-up behaviour in Section 8 is consistent across all supported PSPs from your point of view; BoxPay handles the PSP-specific processing internally.

10. Response Format

BoxPay returns one of three normalized statuses regardless of the underlying PSP:

Approved

{
  "status": { "operation": "Authorisation", "status": "Approved" },
  "pspReference": "1234567890",
  "authCode": "ABC123"
}

RequiresAction (3DS challenge)

{
  "status": { "operation": "Authorisation", "status": "RequiresAction" },
  "actions": [{ "type": "HTML", "htmlContent": "<redirect content for issuer challenge>" }]
}

Rejected

{
  "status": {
    "operation": "Authorisation",
    "status": "Rejected",
    "reason": "Authentication Rejected By Issuer"
  }
}

11. Testing

Use your BoxPay Test environment and Google Pay’s published test cards to validate the hosted checkout flow before go-live, covering both authentication paths: a CRYPTOGRAM_3DS (tokenized) payment and a PAN_ONLY payment with each threeDSAuthentication setting.

12. Google Pay Resources

For reference, Google publishes the following resources for Google Pay on the web:

Google Pay Web developer documentation: https://developers.google.com/pay/api/web/

Google Pay Web integration checklist: https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist

Google Pay Web Brand Guidelines: https://developers.google.com/pay/api/web/guides/brand-guidelines

Note: because BoxPay’s hosted checkout operates the Google Pay integration on your behalf, you are not required to implement the Google Pay Web API or complete the Web integration checklist yourself. The Brand Guidelines apply whenever you reference Google Pay on your own website or marketing materials.

For questions about this integration, contact BoxPay Team.

How can we help?