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

​
Quick Reference

OptionTypeDefaultDescription
buttonTypestring'buy'Button label
buttonColorstring'black'Button color
buttonSizeModestring'fill''fill' or 'static'
buttonRadiusnumber—Corner radius in pixels
buttonBorderTypestring—'default_border' or 'no_border'
buttonLocalestringBrowser defaultISO 639-1 locale code
captureBillingAddressbooleanfalseCapture billing address
captureShippingAddressbooleanfalseCapture shipping address
requireShippingMethodbooleanfalseEnable shipping method selection
emailRequiredbooleanfalseCapture email address
existingPaymentMethodRequiredbooleanfalseOnly 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.
OptionTypeDefaultDescription
buttonTypestring'buy'Button label text (see values below)
buttonColorstring'black''black' for light backgrounds (default), 'white' for dark backgrounds, 'default' (same as 'black')
buttonSizeModestring'fill''fill' to match container width (default), 'static' to size based on label text
buttonRadiusnumber—Corner radius in pixels
buttonBorderTypestring—'default_border' or 'no_border'
buttonLocalestringBrowser defaultISO 639-1 code ('en', 'de', 'fr', etc.)

​
Button Type

Set buttonType to control the label displayed on the Google Pay button.
TypeDescription
'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',
}
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,
  },
}
OptionTypeDescription
captureShippingAddressbooleanEnable shipping address capture
shippingAddressParameters.allowedCountryCodesstring[]ISO 3166-1 alpha-2 country codes
shippingAddressParameters.phoneNumberRequiredbooleanRequire 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

NetworkDescription
VISAVisa cards
MASTERCARDMastercard cards
AMEXAmerican Express cards
DISCOVERDiscover cards
JCBJCB cards
INTERACInterac 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

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)
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)
Checklist:
  • requireShippingMethod: true in SDK options
  • captureShippingAddress: true or shippingAddressParameters set
  • SHIPPING checkout module configured on backend
  • Shipping options available for the selected address
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