Google Pay options

Configuration options for Google Pay payment integration

Google Pay enables customers to pay using payment methods saved to their Google account, including credit/debit cards and other supported payment methods.

Client session requirements

Google Pay requires currencyCode and order.countryCode in the client session.

order.countryCode is the merchant’s country (ISO 3166-1 alpha-2) — where the transaction is processed, not the buyer’s country. This 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).

Quick reference

Option	Type	Default	Description
buttonType	string	'buy'	Button label
buttonColor	string	'black'	Button color
buttonSizeMode	string	'fill'	'fill' or 'static'
buttonRadius	number	—	Corner radius in pixels
buttonBorderType	string	—	'default_border' or 'no_border'
buttonLocale	string	Browser default	ISO 639-1 locale code
captureBillingAddress	boolean	false	Capture billing address
captureShippingAddress	boolean	false	Capture shipping address
requireShippingMethod	boolean	false	Enable shipping method selection
emailRequired	boolean	false	Capture email address
existingPaymentMethodRequired	boolean	false	Only show if user has saved payment

checkout.options = {
  googlePay: {
    buttonType: 'buy',
    buttonColor: 'black',
    buttonSizeMode: 'fill',
    captureBillingAddress: true,
  },
};

---

Button styling

Customize the Google Pay button appearance.

Option	Type	Default	Description
buttonType	string	'buy'	Button label text (see values below)
buttonColor	string	'black'	'black' for light backgrounds (default), 'white' for dark backgrounds, 'default' (same as 'black')
buttonSizeMode	string	'fill'	'fill' to match container width (default), 'static' to size based on label text
buttonRadius	number	—	Corner radius in pixels
buttonBorderType	string	—	'default_border' or 'no_border'
buttonLocale	string	Browser default	ISO 639-1 code ('en', 'de', 'fr', etc.)

Button type

Set buttonType to control the label displayed on the Google Pay button.

Type	Description
'buy'	”Buy with Google Pay” (default)
'checkout'	”Checkout with Google Pay”
'pay'	”Pay with Google Pay”
'order'	”Order with Google Pay”
'book'	”Book with Google Pay”
'donate'	”Donate with Google Pay”
'subscribe'	”Subscribe with Google Pay”
'plain'	Google Pay logo only

Examples

// Standard black button
googlePay: {
  buttonType: 'checkout',
  buttonColor: 'black',
  buttonSizeMode: 'fill',
}

// White button with custom radius
googlePay: {
  buttonType: 'pay',
  buttonColor: 'white',
  buttonRadius: 8,
}

// Localized button (German)
googlePay: {
  buttonType: 'buy',
  buttonLocale: 'de',
}

Supported locales

Google Pay supports: en, ar, bg, ca, cs, da, de, el, es, et, fi, fr, hr, id, it, ja, ko, ms, nl, no, pl, pt, ru, sk, sl, sr, sv, th, tr, uk, zh

---

Express checkout

Google Pay can capture customer information directly from the payment sheet.

Billing address

googlePay: {
  captureBillingAddress: true,
}

The billing address is extracted from the payment data and updated in the client session.

Shipping address

googlePay: {
  captureShippingAddress: true,
  shippingAddressParameters: {
    allowedCountryCodes: ['US', 'CA', 'GB'],
    phoneNumberRequired: true,
  },
}

Option	Type	Description
captureShippingAddress	boolean	Enable shipping address capture
shippingAddressParameters.allowedCountryCodes	string[]	ISO 3166-1 alpha-2 country codes
shippingAddressParameters.phoneNumberRequired	boolean	Require phone number

Providing shippingAddressParameters (even empty {}) implicitly enables shipping address capture for backward compatibility.

Shipping method selection

Enable customers to select shipping methods directly in the Google Pay sheet:

googlePay: {
  captureShippingAddress: true,
  requireShippingMethod: true,
}

When enabled:

• Shipping options from your SHIPPING checkout module appear in the payment sheet
• Customer selects a shipping method before completing payment
• Selected method is sent to your backend via selectShippingMethod()
• Display items update to show shipping costs

requireShippingMethod: true automatically enables shipping address capture — you don’t need to also set captureShippingAddress. Configure your SHIPPING checkout module on the backend to provide available shipping options.

Email capture

googlePay: {
  emailRequired: true,
}

---

Advanced options

Existing payment method required

Only show Google Pay if the user has a saved payment method:

googlePay: {
  existingPaymentMethodRequired: true,
}

Enables one-tap checkout for returning users.

This option only affects button visibility in PRODUCTION. In TEST mode, the button always appears.

---

Supported card networks

Network	Description
VISA	Visa cards
MASTERCARD	Mastercard cards
AMEX	American Express cards
DISCOVER	Discover cards
JCB	JCB cards
INTERAC	Interac cards

Networks are filtered based on your Primer configuration. If orderedAllowedCardNetworks is set in your client session, only those networks are available.

---

Display items

When using express checkout with shipping, the payment sheet displays:

• Line items — Products from order.lineItems
• Fees — Non-zero fees from order.fees
• Shipping — Non-zero shipping costs (when requireShippingMethod is enabled)

If merchantAmount is set, a simplified “Subtotal” view is shown instead.

---

Testing

TEST environment

Google Pay returns mock payment credentials. The button always appears regardless of existingPaymentMethodRequired.

PRODUCTION environment

1. Register your website with the Google Pay Business Console
2. Use a real Google account with saved payment methods
3. Test existingPaymentMethodRequired: true for one-tap checkout

---

Troubleshooting

Google Pay button not appearing

Possible causes:

• Google Pay not configured in Primer Dashboard
• Browser doesn’t support Google Pay
• existingPaymentMethodRequired: true but user has no saved payments (production only)
• Running inside an Android WebView whose host app hasn’t enabled WebView support for Google Pay. Google Pay works inside an Android WebView, but only when the host Android app is configured per Google’s Using Android WebView guide (requires Google Play Services 25.18.30+). In third-party in-app browsers (e.g. Facebook, Instagram, TikTok) that haven’t enabled this, the button won’t appear. No Primer SDK change is needed — this is configured in the host app.

Debug steps:

1. Check browser console for errors
2. Test in Chrome (best Google Pay support)
3. Set existingPaymentMethodRequired: false
4. Verify Google Pay is in your enabledPaymentMethods (if specified)

Shipping methods not appearing

Checklist:

• requireShippingMethod: true in SDK options
• captureShippingAddress: true or shippingAddressParameters set
• SHIPPING checkout module configured on backend
• Shipping options available for the selected address

Address not captured

Checklist:

• captureBillingAddress: true for billing
• captureShippingAddress: true or shippingAddressParameters for shipping
• User has address saved in Google account

---

Complete example

<primer-checkout client-token="your-client-token"></primer-checkout>

<script type="module">
  import { loadPrimer } from '@primer-io/primer-js';

  loadPrimer();

  const checkout = document.querySelector('primer-checkout');
  checkout.options = {
    googlePay: {
      // Styling
      buttonType: 'checkout',
      buttonColor: 'black',
      buttonSizeMode: 'fill',
      buttonRadius: 4,

      // Express checkout
      captureBillingAddress: true,
      captureShippingAddress: true,
      shippingAddressParameters: {
        allowedCountryCodes: ['US', 'CA', 'GB', 'DE', 'FR'],
        phoneNumberRequired: true,
      },
      requireShippingMethod: true,
      emailRequired: true,

      // Advanced
      existingPaymentMethodRequired: false,
    },
  };
</script>

---

See also

SDK options reference

All configuration options

Google Pay web documentation

Official Google documentation

Google Pay button options

Button customization reference