SDK options reference

Complete reference of all SDK configuration options

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

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

Looking for how to use options? See the Options Guide for patterns and best practices.

Quick navigation

Category	Options
Core	locale, merchantDomain, enabledPaymentMethods, disabledPayments
Redirect	redirect.returnUrl, redirect.forceRedirect
Card	card.cardholderName.*
Apple Pay	applePay.buttonOptions.*, applePay.billingOptions, applePay.shippingOptions, applePay.shippingOptions.requireShippingMethod
Google Pay	googlePay.buttonType, googlePay.buttonColor, googlePay.captureShippingAddress, googlePay.requireShippingMethod
Klarna	klarna.paymentFlow, klarna.allowedPaymentCategories
Klarna via Adyen	adyenKlarna.buttonOptions.text
Vault	vault.enabled, vault.headless, vault.showEmptyState
Submit Button	submitButton.amountVisible, submitButton.useBuiltInButton
Stripe	stripe.mandateData, stripe.publishableKey
Legacy	sdkCore

---

Core options

locale

Property	Type	Default
locale	string	Browser’s locale

Sets the UI language. Uses standard locale formats.

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.

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.

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.

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.

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.

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.

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

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.

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

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'

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.

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

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'

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.

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

→ Klarna Options Reference

---

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.

checkout.options = {
  adyenKlarna: {
    buttonOptions: {
      text: 'Pay with Klarna'
    }
  }
};

→ Klarna via Adyen Options Reference

---

PayPal options

PayPal has extensive configuration options documented separately.

→ PayPal Options Reference

---

Vault options

vault.enabled

Property	Type	Default
vault.enabled	boolean	false

Enable payment method vaulting (saving for future use).

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().

checkout.options = {
  vault: {
    enabled: true,
    headless: true
  }
};

→ Headless Vault Implementation Guide

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.

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

---

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.

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.

checkout.options = {
  sdkCore: false  // Use legacy SDK (not recommended)
};

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:

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

Options guide

How to configure options

Events reference

Callbacks and events

Styling variables

CSS customization