> ## 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 }
  }
};
```

<Info>
  **Looking for how to use options?** See the [Options Guide](/checkout/primer-checkout/configuration/sdk-options) for patterns and best practices.
</Info>

## 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](/checkout/primer-checkout/configuration/localization).

### 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
    }
  }
};
```

<Info>
  For runtime updates after initialization, use `primer.setCardholderName()`.
</Info>

***

## Apple Pay options

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

### 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](/sdk/primer-checkout-web/apple-pay#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](/sdk/primer-checkout-web/google-pay).

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

### 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](/sdk/primer-checkout-web/klarna)

***

## 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](/sdk/primer-checkout-web/adyen-klarna)

***

## PayPal options

PayPal has extensive configuration options documented separately.

→ [PayPal Options Reference](/sdk/primer-checkout-web/paypal)

***

## 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](/sdk/primer-checkout-web/components/primer-vault-manager#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](/checkout/primer-checkout/guides-and-recipes/external-submit-button)

***

## Stripe options

### stripe.publishableKey

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

Stripe publishable key for direct integration.

### stripe.mandateData

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

Custom mandate text for direct debit payments.

```javascript theme={"dark"}
checkout.options = {
  stripe: {
    publishableKey: 'pk_test_...',
    mandateData: {
      fullMandateText: 'By providing your payment information...',
      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.
</Warning>

***

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

<CardGroup cols={2}>
  <Card title="Options guide" icon="gear" href="/checkout/primer-checkout/configuration/sdk-options">
    How to configure options
  </Card>

  <Card title="Events reference" icon="bolt" href="/sdk/primer-checkout-web/events-reference">
    Callbacks and events
  </Card>

  <Card title="Styling variables" icon="palette" href="/sdk/primer-checkout-web/styling-variables">
    CSS customization
  </Card>
</CardGroup>