Skip to content

Google Pay

Withdraw funds using stored Google Pay card-on-file device tokens.

Overview

Google Pay in Payout Drop-in is a stored-instrument flow. The accordion lists vaulted Google Pay device tokens for the authenticated shopper. The shopper selects a token and submits the withdrawal. Drop-in uses those vaulted tokens only; it doesn't open a Google Pay payment sheet.

Key benefits

This method gives you:

  • Stored token selection: Shoppers choose from eligible Google Pay vault tokens already on file.
  • Unified callbacks: Same onBeforeSubmit, onSubmit, onSuccess, and onError pattern as card and Apple Pay card-on-file methods.
  • No CVC: Card-on-file payout submit doesn't require CVC for these tokens.
  • Token maintenance: Where the list UI allows it, shoppers can delete tokens and edit expiry.
  • Branding: Panel styling comes from your payout site configuration.

How it works

The flow works like this:

  1. Your payout session allows Google Pay under allowedFundingTypes.wallets.googlePay.
  2. You return a shopper ID from onGetShopper.
  3. Drop-in loads active tokens and keeps only Google Pay device tokens that aren't expired or blacklisted.
  4. If at least one token remains, Google Pay appears in the accordion.
  5. The shopper selects a token and confirms the withdrawal.
  6. Optional onBeforeSubmit and onSubmit run, then payout initiation completes with onSuccess or onError.

If every method is filtered out, Drop-in reports SDK1701.

Session requirements

Google Pay must be allowed on the payout session through allowedFundingTypes.wallets.googlePay. The SDK treats Google Pay as a candidate method when the googlePay object is present. Values such as merchantId or merchantName may appear on that object when Google Pay is enabled for the site; this panel uses vaulted device tokens only.

Example session fragment:

{
  "allowedFundingTypes": {
    "wallets": {
      "googlePay": {}
    }
  }
}

Match transactionData.amount and transactionData.currency to the payout session amounts.

Shopper and token requirements

Google Pay appears only when these shopper and token checks pass:

RequirementDescription
onGetShopperThe authenticated shopper ID used by the token vault. Without it, token retrieval is skipped and Google Pay won't appear.
Wallet typeThe token walletType must be GooglePay.
PAN typeThe token panType must be Device.
ExpiryWhether the token is still in date. Expired tokens are filtered out. The current month remains valid.
BlacklistTokens listed in methodConfig.googlePay.blacklistedInstruments are hidden.

After filtering, Drop-in shows up to five tokens, ranked by most recent successful purchase or payout activity.

Token loading

When Google Pay is a candidate and a shopper ID is present, Drop-in retrieves active tokens for ownerType MerchantGroup (set during initialisation) and your configured ownerId, for that shopper.

Typical path:

GETT
/v1/token-vault/{ownerType}/{ownerId}/merchant-shoppers/{shopperId}/active-tokens

From that shared list, Google Pay keeps tokens with walletType GooglePay and panType Device only. If the token call fails or returns nothing usable for Google Pay, the method is omitted without necessarily calling onError.

Showing a token in Drop-in doesn't authorise the payout. Confirm amount, destination, and eligibility on your backend before treating the withdrawal as complete.

Configuration

Use methodConfig.googlePay for blacklists only.

Blacklist stored instruments

Use blacklistedInstruments to hide specific tokens from the Google Pay panel:

import type { PayoutDropInMethodConfig } from '@pxpio/web-components-sdk';

const methodConfig: PayoutDropInMethodConfig = {
  googlePay: {
    blacklistedInstruments: {
      gatewayTokenIds: ['<GATEWAY_TOKEN_ID>'],
      schemeTokenIds: ['<SCHEME_TOKEN_ID>'],
    },
  },
};

blacklistedInstruments accepts:

PropertyDescription
gatewayTokenIdsThe gateway token IDs to hide from the panel.
schemeTokenIdsThe scheme token IDs to hide from the panel.

Blacklisting hides instruments in the accordion. When closed-loop enforcement is active, the same blacklist values are also sent on the closed-loop allocation request. Confirm payout eligibility on your backend.

Localisation

Override the accordion label:

localisation: {
  payoutDropIn: {
    googlePayLabel: 'Google Pay',
  },
},

Implementation

The following example initialises Drop-in for a Google Pay payout, including optional onBeforeSubmit and onSubmit hooks on the card-on-file path:

import {
  PayoutDropIn,
  type PayoutDropInSubmitResult,
} from '@pxpio/web-components-sdk';
import type { BaseSdkException } from '@pxpio/web-components-sdk';

const payoutDropIn = PayoutDropIn.initialize({
  environment: 'test',
  session: sessionData,
  ownerId: 'YOUR-MERCHANT-GROUP-ID',
  transactionData: {
    currency: 'USD',
    amount: 40,
    entryType: 'Ecom',
    merchantTransactionId: crypto.randomUUID(),
    merchantTransactionDate: () => new Date().toISOString(),
  },
  onGetShopper: async () => ({ id: 'shopper-123' }),
  onBeforeSubmit: async (payoutMethod) => {
    if (payoutMethod !== 'GooglePay') {
      return true;
    }
    return confirmWithdrawal();
  },
  onSubmit: (payoutMethod) => {
    if (payoutMethod === 'GooglePay') {
      showLoading(true);
    }
  },
  onSuccess: async (result: PayoutDropInSubmitResult) => {
    showLoading(false);
    console.log('Google Pay payout submitted', result.systemTransactionId);
    console.log('Payout method', result.payoutMethod);
    await verifyPayoutOnBackend(result);
  },
  onError: (error: BaseSdkException) => {
    showLoading(false);
    console.error(error.ErrorCode, error.message);
  },
});

await payoutDropIn.create('payout-drop-in-container');

Success and verification

On success, onSuccess receives a PayoutDropInSubmitResult with at least:

PropertyDescription
systemTransactionIdThe PXP system transaction ID.
merchantTransactionIdYour merchant transaction ID.
payoutMethodGooglePay for this method.

Treat onSuccess as submission acknowledgement. Verify the transaction with your webhook handler or a server-side lookup before updating the shopper's withdrawal status.

A successful Google Pay payout merchant webhook looks like this:

{ "eventDate": "2025-12-16T07:37:11.1613200Z", "eventCategory": "transaction", "eventData": { "state": "Authorised", "amount": { "transaction": 40, "currencyCode": "USD" }, "transactionMethod": "Payout", "merchant": "merchant-1", "site": "site-1", "merchantTransactionDate": "2025-12-16T07:37:11.1613200Z", "merchantTransactionId": "GOOGLEPAY-PAYOUT-001", "systemTransactionId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "fundingData": { "card": { … } } } }

See Quickstart for the end-to-end session and reconciliation pattern, and Manage webhooks for subscription and signature validation.

Gaming eligibility

Card gaming payout token rules aren't automatically applied to Google Pay token filtering in Drop-in. Don't assume card gaming rules extend to Google Pay without backend confirmation.

Error handling

These codes are the ones you're most likely to see on the Google Pay path:

CodeTypical Google Pay context
SDK1701No payout methods remain (e.g., no eligible Google Pay device tokens and no other methods).
SDK1703Card-on-file payout initiation failed. Inspect message and details; correlate with backend transaction state.

See Error handling.

Testing

Validate the path with these steps:

  1. Use environment: 'test' with sandbox credentials.
  2. Prepare a test shopper that already has a Google Pay device token in the vault (walletType: GooglePay, panType: Device).
  3. Create a payout session with allowedFundingTypes.wallets.googlePay enabled.
  4. Confirm the Google Pay accordion appears, token selection works, and submit reaches onSuccess or a clear SDK1703.
  5. Verify the transaction on your backend before treating the withdrawal as complete.

See Testing.