> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> `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`](https://developers.google.com/pay/api/web/reference/request-objects#TransactionInfo): "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 |

```javascript theme={"dark"}
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](#button-type) 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

```javascript theme={"dark"}
// 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',
}
```

> [accordion] 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

```javascript theme={"dark"}
googlePay: {
  captureBillingAddress: true,
}
```

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

### Shipping address

```javascript theme={"dark"}
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 |

> [!NOTE]
>
> 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:

```javascript theme={"dark"}
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

> [!TIP]
>
> `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

```javascript theme={"dark"}
googlePay: {
  emailRequired: true,
}
```

***

## Advanced options

### Existing payment method required

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

```javascript theme={"dark"}
googlePay: {
  existingPaymentMethodRequired: true,
}
```

Enables one-tap checkout for returning users.

> [!NOTE]
>
> 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](https://pay.google.com/business/console/)
2. Use a real Google account with saved payment methods
3. Test `existingPaymentMethodRequired: true` for one-tap checkout

***

## Troubleshooting

> [accordion] 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](https://developers.google.com/pay/api/android/guides/recipes/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)

> [accordion] 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

> [accordion] Address not captured
>
> **Checklist:**
>
> * [ ] `captureBillingAddress: true` for billing
> * [ ] `captureShippingAddress: true` or `shippingAddressParameters` for shipping
> * [ ] User has address saved in Google account

***

## Complete example

```html theme={"dark"}
<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

> [card] [SDK options reference](https://primer.io/docs/sdk/primer-checkout-web/sdk-options-reference.md)
>
> All configuration options

> [card] [Google Pay web documentation](https://developers.google.com/pay/api/web)
>
> Official Google documentation

> [card] [Google Pay button options](https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions)
>
> Button customization reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.