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

# SDK options reference

> Complete reference of all SDK configuration options

This reference documents all options available in the `options` property of `<primer-checkout>`.

```javascript theme={"dark"}
const checkout = document.querySelector('primer-checkout');

checkout.setAttribute('client-token', 'your-token'); // Component property
checkout.options = {                                  // SDK options
  locale: 'en-GB',
  card: {
    cardholderName: { required: true }
  }
};
```

> [!NOTE]
>
> **Looking for how to use options?** See the [Options Guide](https://primer.io/docs/checkout/primer-checkout/configuration/sdk-options.md) for patterns and best practices.

## Quick navigation

| Category | Options |
| - | - |
| [Core](#core-options) | `locale`, `merchantDomain`, `enabledPaymentMethods`, `disabledPayments` |
| [Redirect](#redirect-options) | `redirect.returnUrl`, `redirect.forceRedirect` |
| [Card](#card-options) | `card.cardholderName.*` |
| [Apple Pay](#apple-pay-options) | `applePay.buttonOptions.*`, `applePay.billingOptions`, `applePay.shippingOptions`, `applePay.shippingOptions.requireShippingMethod` |
| [Google Pay](#google-pay-options) | `googlePay.buttonType`, `googlePay.buttonColor`, `googlePay.captureShippingAddress`, `googlePay.requireShippingMethod` |
| [Klarna](#klarna-options) | `klarna.paymentFlow`, `klarna.allowedPaymentCategories` |
| [Klarna via Adyen](#klarna-via-adyen-options) | `adyenKlarna.buttonOptions.text` |
| [Vault](#vault-options) | `vault.enabled`, `vault.headless`, `vault.showEmptyState` |
| [Submit Button](#submit-button-options) | `submitButton.amountVisible`, `submitButton.useBuiltInButton` |
| [Stripe](#stripe-options) | `stripe.mandateData`, `stripe.publishableKey` |
| [Legacy](#legacy-options) | `sdkCore` |

***

## Core options

### locale

| Property | Type | Default |
| - | - | - |
| `locale` | `string` | Browser's locale |

Sets the UI language. Uses standard locale formats.

```javascript theme={"dark"}
checkout.options = {
  locale: 'en-GB'
};
```

Supported locales include: `en-US`, `en-GB`, `fr-FR`, `de-DE`, `es-ES`, `it-IT`, `nl-NL`, `pt-BR`, `ja-JP`, and [40+ more](https://primer.io/docs/checkout/primer-checkout/configuration/localization.md).

### merchantDomain

| Property | Type | Default |
| - | - | - |
| `merchantDomain` | `string` | `window.location.hostname` |

Domain for Apple Pay validation. Set this when checkout is hosted on a different domain than your registered Apple Pay domain.

```javascript theme={"dark"}
checkout.options = {
  merchantDomain: 'merchant.example.com'
};
```

### enabledPaymentMethods

| Property | Type | Default |
| - | - | - |
| `enabledPaymentMethods` | `PaymentMethodType[]` | All configured methods |

Filters which payment methods are displayed. Methods must also be configured in your Primer Dashboard.

```javascript theme={"dark"}
import { PaymentMethodType } from '@primer-io/primer-js';

checkout.options = {
  enabledPaymentMethods: [
    PaymentMethodType.PAYMENT_CARD,
    PaymentMethodType.PAYPAL,
    PaymentMethodType.ADYEN_BLIK,
  ]
};
```

### disabledPayments

| Property | Type | Default |
| - | - | - |
| `disabledPayments` | `boolean` | `false` |

Disables all payment methods. Useful when you only want to show vaulted payment methods.

```javascript theme={"dark"}
checkout.options = {
  disabledPayments: true
};
```

***

## Redirect options

Configuration for redirect-based payment methods. Controls the return URL behavior for payment methods that require a redirect to an external page (e.g. PayPal, Klarna, and most APMs), and whether to force a full-page redirect instead of opening the flow in a popup where supported.

### redirect.returnUrl

| Property | Type | Default |
| - | - | - |
| `redirect.returnUrl` | `string` | Current page URL |

URL the payment method redirects back to after the customer completes (or cancels) the flow on the external page. If omitted, the SDK uses the current page URL.

### redirect.forceRedirect

| Property | Type | Default |
| - | - | - |
| `redirect.forceRedirect` | `boolean` | `false` |

Whether to force a full-page redirect for payment methods that would otherwise open in a popup.

```javascript theme={"dark"}
checkout.options = {
  redirect: {
    returnUrl: 'https://merchant.example.com/checkout/return',
    forceRedirect: true,
  }
};
```

***

## Card options

### card.cardholderName

| Property | Type | Default |
| - | - | - |
| `card.cardholderName.required` | `boolean` | `false` |
| `card.cardholderName.visible` | `boolean` | `true` |
| `card.cardholderName.defaultValue` | `string` | none |

Configure the cardholder name field.

```javascript theme={"dark"}
checkout.options = {
  card: {
    cardholderName: {
      required: true,
      visible: true,
      defaultValue: 'John Doe'  // Pre-fill the field
    }
  }
};
```

> [!NOTE]
>
> For runtime updates after initialization, use `primer.setCardholderName()`.

***

## Apple Pay options

For complete Apple Pay configuration including all button types, testing, and requirements, see the [Apple Pay Options Reference](https://primer.io/docs/sdk/primer-checkout-web/apple-pay.md).

### applePay.buttonOptions

| Property | Type | Default |
| - | - | - |
| `applePay.buttonOptions.type` | `string` | `'plain'` |
| `applePay.buttonOptions.buttonStyle` | `string` | — |

**Button types:** `'plain'`, `'buy'`, `'book'`, `'check-out'`, `'donate'`, `'order'`, `'pay'`, `'set-up'`, `'subscribe'`, and [more](https://primer.io/docs/sdk/primer-checkout-web/apple-pay.md#button-type)

**Button styles:** `'black'`, `'white'`, `'white-outline'`. If not set, Apple Pay uses its default styling.

### applePay.billingOptions

| Property | Type | Default |
| - | - | - |
| `applePay.billingOptions.requiredBillingContactFields` | `string[]` | `[]` |

Values: `'postalAddress'`

### applePay.shippingOptions

| Property | Type | Default |
| - | - | - |
| `applePay.shippingOptions.requiredShippingContactFields` | `string[]` | `[]` |
| `applePay.shippingOptions.requireShippingMethod` | `boolean` | `false` |

**Contact fields:** `'postalAddress'`, `'name'`, `'phoneticName'`, `'phone'`, `'email'`

```javascript theme={"dark"}
checkout.options = {
  applePay: {
    buttonOptions: {
      type: 'buy',
      buttonStyle: 'black'
    },
    billingOptions: {
      requiredBillingContactFields: ['postalAddress']
    },
    shippingOptions: {
      requiredShippingContactFields: ['postalAddress', 'name', 'email'],
      requireShippingMethod: true
    }
  }
};
```

***

## Google Pay options

For complete Google Pay configuration including express checkout, shipping methods, and testing, see the [Google Pay Options Reference](https://primer.io/docs/sdk/primer-checkout-web/google-pay.md).

### googlePay.buttonType

| Property | Type | Default |
| - | - | - |
| `googlePay.buttonType` | `string` | `'buy'` |

Values: `'buy'`, `'checkout'`, `'pay'`, `'order'`, `'book'`, `'donate'`, `'subscribe'`, `'plain'`

### googlePay.buttonColor

| Property | Type | Default |
| - | - | - |
| `googlePay.buttonColor` | `string` | `'black'` |

Values: `'black'`, `'white'`, `'default'`

### googlePay.buttonSizeMode

| Property | Type | Default |
| - | - | - |
| `googlePay.buttonSizeMode` | `string` | `'fill'` |

Values: `'fill'` (expands to container), `'static'` (sized by label)

### googlePay.buttonRadius

| Property | Type | Default |
| - | - | - |
| `googlePay.buttonRadius` | `number` | — |

Corner radius in pixels.

### googlePay.buttonLocale

| Property | Type | Default |
| - | - | - |
| `googlePay.buttonLocale` | `string` | Browser default |

ISO 639-1 locale code (e.g., `'en'`, `'de'`, `'fr'`).

### googlePay.captureBillingAddress

| Property | Type | Default |
| - | - | - |
| `googlePay.captureBillingAddress` | `boolean` | `false` |

### googlePay.captureShippingAddress

| Property | Type | Default |
| - | - | - |
| `googlePay.captureShippingAddress` | `boolean` | `false` |

### googlePay.shippingAddressParameters

| Property | Type | Default |
| - | - | - |
| `googlePay.shippingAddressParameters.allowedCountryCodes` | `string[]` | — |
| `googlePay.shippingAddressParameters.phoneNumberRequired` | `boolean` | `false` |

### googlePay.requireShippingMethod

| Property | Type | Default |
| - | - | - |
| `googlePay.requireShippingMethod` | `boolean` | `false` |

Enable shipping method selection in the Google Pay sheet. Requires `captureShippingAddress` or `shippingAddressParameters`.

### googlePay.emailRequired

| Property | Type | Default |
| - | - | - |
| `googlePay.emailRequired` | `boolean` | `false` |

### googlePay.existingPaymentMethodRequired

| Property | Type | Default |
| - | - | - |
| `googlePay.existingPaymentMethodRequired` | `boolean` | `false` |

Only show button if user has a saved payment method (production only).

```javascript theme={"dark"}
checkout.options = {
  googlePay: {
    buttonType: 'buy',
    buttonColor: 'black',
    buttonSizeMode: 'fill',
    captureBillingAddress: true,
    captureShippingAddress: true,
    requireShippingMethod: true,
    emailRequired: true
  }
};
```

***

## Klarna options

### klarna.paymentFlow

| Property | Type | Default |
| - | - | - |
| `klarna.paymentFlow` | `string` | `'DEFAULT'` |

Values: `'DEFAULT'`, `'PREFER_VAULT'`

> [!NOTE]
>
> When using `'PREFER_VAULT'`, you must also provide `klarna.recurringPaymentDescription`.

### klarna.recurringPaymentDescription

| Property | Type | Default |
| - | - | - |
| `klarna.recurringPaymentDescription` | `string` | none |

Required when offering recurring payments.

### klarna.allowedPaymentCategories

| Property | Type | Default |
| - | - | - |
| `klarna.allowedPaymentCategories` | `string[]` | All categories |

Values: `'pay_now'`, `'pay_later'`, `'pay_over_time'`

### klarna.buttonOptions.text

| Property | Type | Default |
| - | - | - |
| `klarna.buttonOptions.text` | `string` | none |

Custom button text.

```javascript theme={"dark"}
checkout.options = {
  klarna: {
    paymentFlow: 'DEFAULT',
    allowedPaymentCategories: ['pay_now', 'pay_later'],
    buttonOptions: {
      text: 'Pay with Klarna'
    }
  }
};
```

→ [Klarna Options Reference](https://primer.io/docs/sdk/primer-checkout-web/klarna.md)

***

## Klarna via Adyen options

### adyenKlarna.buttonOptions.text

| Property | Type | Default |
| - | - | - |
| `adyenKlarna.buttonOptions.text` | `string` | none |

Custom text displayed next to the Klarna logo. Replaces the default "Pay with" text.

```javascript theme={"dark"}
checkout.options = {
  adyenKlarna: {
    buttonOptions: {
      text: 'Pay with Klarna'
    }
  }
};
```

→ [Klarna via Adyen Options Reference](https://primer.io/docs/sdk/primer-checkout-web/adyen-klarna.md)

***

## PayPal options

PayPal has extensive configuration options documented separately.

→ [PayPal Options Reference](https://primer.io/docs/sdk/primer-checkout-web/paypal.md)

***

## Vault options

### vault.enabled

| Property | Type | Default |
| - | - | - |
| `vault.enabled` | `boolean` | `false` |

Enable payment method vaulting (saving for future use).

```javascript theme={"dark"}
checkout.options = {
  vault: {
    enabled: true
  }
};
```

### vault.headless

| Property | Type | Default |
| - | - | - |
| `vault.headless` | `boolean` | `false` |

Hides default vault UI for custom implementations. Use with `onVaultedMethodsUpdate`, `vault.createCvvInput()`, and `vault.startPayment()`.

```javascript theme={"dark"}
checkout.options = {
  vault: {
    enabled: true,
    headless: true
  }
};
```

→ [Headless Vault Implementation Guide](https://primer.io/docs/sdk/primer-checkout-web/components/primer-vault-manager.md#headless-vault-implementation)

### vault.showEmptyState

| Property | Type | Default |
| - | - | - |
| `vault.showEmptyState` | `boolean` | `false` |

Show a message when no saved payment methods exist.

***

## Submit button options

### submitButton.amountVisible

| Property | Type | Default |
| - | - | - |
| `submitButton.amountVisible` | `boolean` | `false` |

Show the order amount on the button (e.g., "Pay \$12.34").

### submitButton.useBuiltInButton

| Property | Type | Default |
| - | - | - |
| `submitButton.useBuiltInButton` | `boolean` | `true` |

Set to `false` to use your own submit button. Dispatch `primer:card-submit` event to trigger submission.

```javascript theme={"dark"}
// Use external button
checkout.options = {
  submitButton: {
    useBuiltInButton: false
  }
};

// Your button triggers submission
document.getElementById('my-button').addEventListener('click', () => {
  document.dispatchEvent(new CustomEvent('primer:card-submit', {
    bubbles: true,
    composed: true
  }));
});
```

→ [External Submit Button Recipe](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/external-submit-button.md)

***

## Stripe options

### stripe.publishableKey

| Property | Type | Default |
| - | - | - |
| `stripe.publishableKey` | `string` | none |

Stripe publishable key, required for [ACH via Stripe](https://primer.io/docs/connections/payment-methods/ach/stripe.md). It must belong to the Stripe account connected to your Primer Dashboard. In sandbox, use the test mode key.

### stripe.mandateData

| Property | Type | Default |
| - | - | - |
| `stripe.mandateData.fullMandateText` | `string` | none |
| `stripe.mandateData.merchantName` | `string` | none |

The mandate the shopper accepts before an ACH payment. Required for ACH via Stripe: without it, ACH is not shown. Pass one of:

* `merchantName`: your business name, inserted into Primer's default mandate text.
* `fullMandateText`: your own mandate text, replacing the default.

```javascript theme={"dark"}
checkout.options = {
  stripe: {
    publishableKey: 'pk_test_...',
    mandateData: {
      merchantName: 'Your Business',
    },
  },
};
```

***

## Legacy options

### sdkCore

| Property | Type | Default |
| - | - | - |
| `sdkCore` | `boolean` | `true` |

SDK Core is the default payment engine. Set to `false` only if you need legacy behavior.

```javascript theme={"dark"}
checkout.options = {
  sdkCore: false  // Use legacy SDK (not recommended)
};
```

> [!WARNING]
>
> Only set `sdkCore: false` if you have a specific need for legacy behavior. SDK Core is the recommended engine for all new integrations.

***

## TypeScript

Import types for autocomplete and type checking:

```typescript theme={"dark"}
import type { PrimerCheckoutOptions } from '@primer-io/primer-js';
import { PaymentMethodType } from '@primer-io/primer-js';

const options: PrimerCheckoutOptions = {
  locale: 'en-GB',
  enabledPaymentMethods: [PaymentMethodType.PAYMENT_CARD]
};

checkout.options = options;
```

## See also

> [card] [Options guide](https://primer.io/docs/checkout/primer-checkout/configuration/sdk-options.md)
>
> How to configure options

> [card] [Events reference](https://primer.io/docs/sdk/primer-checkout-web/events-reference.md)
>
> Callbacks and events

> [card] [Styling variables](https://primer.io/docs/sdk/primer-checkout-web/styling-variables.md)
>
> CSS customization


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