> ## 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).
</Note>

## 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 title="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`
</Accordion>

***

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

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

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

***

## 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 title="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)

  **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>

<Accordion title="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>

<Accordion title="Address not captured">
  **Checklist:**

  * [ ] `captureBillingAddress: true` for billing
  * [ ] `captureShippingAddress: true` or `shippingAddressParameters` for shipping
  * [ ] User has address saved in Google account
</Accordion>

***

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

<CardGroup cols={2}>
  <Card title="SDK options reference" icon="gear" href="/sdk/primer-checkout-web/sdk-options-reference">
    All configuration options
  </Card>

  <Card title="Google Pay web documentation" icon="arrow-up-right-from-square" href="https://developers.google.com/pay/api/web">
    Official Google documentation
  </Card>

  <Card title="Google Pay button options" icon="arrow-up-right-from-square" href="https://developers.google.com/pay/api/web/reference/request-objects#ButtonOptions">
    Button customization reference
  </Card>
</CardGroup>