Google Pay™

In a nutshell

Allow customers to securely make payments using Google Pay on Android devices and most browsers.

Google Pay is available on most browsers (Chrome, Microsoft Edge, Brave, Safari, and Firefox) across desktop and Android. Paystack currently supports Google Pay for web merchants only, including on Android devices via Chromium browsers.

Paystack accepts two Google Pay authorization methods, both enabled by default. Merchants can't turn either one on or off individually:

• CRYPTOGRAM_3DS: for cards device-tokenized in Google Wallet on Android. It includes an on-device cryptogram, so no separate 3DS step-up is required, and liability shift applies by default.
• PAN_ONLY: for cards saved to a Google Account but not device-tokenized. Paystack runs a 3DS step-up on every PAN_ONLY charge to preserve liability shift where the card issuer supports it. No merchant configuration is needed. Paystack applies this step automatically.

When the sheet loads, Paystack prioritises CRYPTOGRAM_3DS for Android and Chromium, and falls back to PAN_ONLY everywhere else. Paystack configures this list, known as Google Pay's allowedCardNetworks, directly. Merchants don't set it themselves. Visa and Mastercard are the only networks currently supported.

Activating Google Pay

You can configure the Google Pay channel for your web app on the Paystack Dashboard. To enable Google Pay on your integration, go to the Preferences page on the Paystack Dashboard and check the Google Pay option.

If you use Commerce Suite (Invoices, Payment Pages, or Storefronts) or any plugin that redirects customers away from your site to a new page for payment, Google Pay becomes available there once enabled. Merchants with a custom web app should continue to the next section to set up Google Pay for their website.

Setting up on Popup

This method doesn't require any additional HTML elements, since Paystack does the heavy lifting for you. Tie your payment button to the checkout() method:

1const paystackPop = new PaystackPop();
2
3async function payWithPaystack() {
4  await paystackPop.checkout({
5    key: 'pk_domain_xxxxx',
6    email: '[email protected]',
7    amount: 10000,
8    onSuccess: (transaction) => {
9      console.log('Transaction: ', transaction)
10    },
11    onCancel: () => {
12      console.log('Pop up closed!')
13    }
14  })
15}

The checkout method detects whether the customer's browser supports Google Pay. If it does, Paystack surfaces the Google Pay button automatically in the pre-checkout modal alongside a button to load other payment options. Otherwise, the checkout loads without it.

Building a custom Google Pay checkout

Set up your Google Pay merchant profile

Follow Google's official guides to create and publish your integration:

1. Set up your Google Pay integration: create your Google Pay & Wallet Console account and configure your integration. Aim for a WEB and GATEWAY integration.
2. Publish your integration: move your integration out of TEST and into PRODUCTION so it can process real transactions.

Once Google approves your integration, get the following from the Google Pay & Wallet Console and configure them on the Google Pay SDK under the merchantInfo object (as detailed below) when you initiate checkout:

• merchantId: your production Google Pay merchant identifier (typically a 15-16 character string, for example BCR2DN7T...). Visible on your Google Pay & Wallet Console.
• merchantName: the business name that appears on the Google Pay & Wallet Console.
• merchantOrigin: the origin for your web integration as registered with Google.

Using Google Pay SDK

When using the Google Pay SDK, you build the PaymentDataRequest with the following defaults:

1{
2  "apiVersion": 2,
3  "apiVersionMinor": 0,
4  "allowedPaymentMethods": [{
5    "type": "CARD",
6    "parameters": {
7      "allowedAuthMethods": ["CRYPTOGRAM_3DS", "PAN_ONLY"],
8      "allowedCardNetworks": ["VISA", "MASTERCARD"],
9      "billingAddressRequired": true,
10      "billingAddressParameters": { 
11        "format": "FULL", 
12        "phoneNumberRequired": false 
13      },
14      "assuranceDetailsRequired": true
15    },
16    "tokenizationSpecification": {
17      "type": "PAYMENT_GATEWAY",
18      "parameters": {
19        "gateway": "paystack",
20        "gatewayMerchantId": "YOUR_PAYSTACK_INTEGRATION_ID"
21      }
22    }
23  }],
24  "merchantInfo": {
25    "merchantName": "YOUR_BUSINESS_NAME",
26    "merchantId": "BCR2DN7TTCZK3ED6",
27    "merchantOrigin": "www.business-website.com"
28  }
29}

Key values you should consider:

• tokenizationSpecification.parameters.gateway: Paystack's registered Google Pay gateway identifier.
• tokenizationSpecification.parameters.gatewayMerchantId: your Paystack integration id from your dashboard.
• allowedAuthMethods: ['CRYPTOGRAM_3DS', 'PAN_ONLY']: both are enabled together so Paystack can serve every browser.
• allowedCardNetworks: ['VISA', 'MASTERCARD']: the card networks Paystack currently processes for Google Pay.
• billingAddressRequired: true: Paystack requires a full billing address (street, city, region, postcode, country) on every Google Pay charge. Phone number is not required. See the Google reference for the BillingAddressParameters shape.
• assuranceDetailsRequired: true: ensures Google Pay returns the cardHolderAuthenticated signal on the payment, which drives Paystack's downstream 3DS decision on PAN_ONLY tokens.

Charging a token

With your integration approved and the Google Pay button on your website, customers can interact with the button and select their preferred card. Google Pay then encrypts those card details into a token, which it forwards to Paystack (as the gateway selected under tokenizationSpecification) to decrypt and charge.

Charging an existing token uses the Google Pay Charge endpoint (googlepay/charge), but most integrations should route through Paystack's checkout instead. This section documents the endpoint for completeness.

Send the payload as application/x-www-form-urlencoded:

Field	Required	Notes
transaction	Yes	Paystack transaction id from Initialize TransactionAPI.
paymentObject	Yes	The full paymentData object returned by loadPaymentData(), JSON-encoded as a single form value.
device	No	Device fingerprint, if you collect one.

The response follows Paystack's standard charge response structure. The list below shows the expected value of status and the meaning:

• success: Paystack authorizes the charge inline. Typical for CRYPTOGRAM_3DS.
• auth: the charge requires a 3DS step-up. Typical for PAN_ONLY. Open data.otpmessage in an iframe and subscribe to the Pusher channel 3DS_<transactionId>, event response, for the final result.
• failed: the card issuer declined the charge, or Paystack rejected the token. message carries a customer-safe reason.

Recurring transactions

Once Paystack authorizes a Google Pay charge, you can process subsequent merchant-initiated charges (Subscriptions, Recurring Charges) against the resulting authorization code, similar to recurring card charges. See Recurring Charges for the full flow.

Refunds

Google Pay refunds work identically to card refunds. Paystack supports partial refunds. See Refunds for how to create and manage a refund.

Troubleshooting

If you experience any issues with your Google Pay integration, ensure there wasn't an oversight during setup:

• Your server must serve all requests via HTTPS in production
• Google Pay is enabled on your integration under the Preferences page

If all checks out and you are still having issues with your Google Pay integration, here are some possible errors and resolutions you can try out:

Error	Resolution
Merchant's Category not supported for Google Pay	For compliance reasons, Paystack allows only specific business categories to use Google Pay. Please reach out to [email protected] for more information
Invalid Google Payment Data Received	The paymentObject sent to /googlepay/charge is missing required fields or has malformed data. Escalate this to [email protected] with the payload sent to this endpoint.
Merchant identifier mismatch	The gatewayMerchantId embedded in the Google Pay token doesn't match the Paystack integration id on the transaction. Confirm you generated both from the same Paystack integration.
An error occurred while processing request	Generic failure, Paystack failed to decrypt the token or the transaction lifecycle hit an internal error. Retry the charge; if the issue persists, contact Paystack Support with the transaction reference.