Primer Docs

1configure(options: HeadlessUniversalCheckoutOptions): void

copy

Configure the Headless Checkout instance with the provided options.

Parameters

optionsobject

Options for a Headless Universal Checkout, its properties can be defined to configure the checkout experience.

Callbacks

onAvailablePaymentMethodsLoad(paymentMethods: PaymentMethodInfo[]) => voidRequired

Called when the available payment methods have been loaded. Takes an array of objects as its argument.

PaymentMethodInfo

typePaymentMethodTypeRequired

The type of payment method, one of PaymentMethodType.

managerType"CARD" | "NATIVE" | "REDIRECT"Required

The type of payment manager to use.

Properties

containerstring | ElementRequired

A CSS selector or an element where the UI will be mounted.

localestring

Specifies the locale to use for the checkout experience. See list of ISO 639 codes.

styleCheckoutStyle

Define the styling for the checkout experience.

sceneobject

Options for customizing the transition animations between payment form scenes.

Properties

onEntering(sceneId: string) => void

Called when entering a new scene. The function is passed the ID of the new scene as an argument.

transitionobject | false

errorMessageobject

Options for customizing the display of error messages.

Properties

disabledboolean

Whether error messages should be disabled.

Callbacks

onErrorMessageShow(message: string) => void

Called when an error message is shown. The function is passed the error message as an argument.

onErrorMessageHide() => void

Called when an error message is hidden.

formobject

Options for customizing the form fields.

Properties

inputLabelsVisibleboolean

Whether the labels for form inputs should be visible.

submitButtonobject

Options for configuring the submit button.

Properties

amountVisibleboolean

Whether to show the amount on the submit button.

useBuiltInButtonboolean

Whether to use the built-in submit button.

Callbacks

onVisible(isVisible: boolean, context: Context) => void

Called whenever the visibility of the submit button changes.

contextobject

currentSceneIdstring

previousSceneIdstring

onContentChange(content: string, context: Context) => void

Called whenever the content of the submit button changes.

contextobject

currentSceneIdstring

onDisable(isDisabled: boolean, context: Context) => void

Called whenever the disable state of the submit button changes.

contextobject

currentSceneIdstring

onLoading(isLoading: boolean, context: Context) => void

Called whenever the loading state of the submit button changes.

contextobject

currentSceneIdstring

processingIndicatorobject

A configuration object for the processing indicator.

Properties

visibleboolean

Whether the processing indicator should be visible or not.

allowedCardNetworksCardNetwork[]

Allowed card networks for credit card payments, one of CardNetwork.

cardobject

Customize the appearance and behavior of the card fields in the checkout form.

Properties

cardholderNameobject

Options for the cardholder name input field.

Properties

requiredboolean

Whether the cardholder name is required. Only works if the cardholder name is visible.

visiblebooleanDeprecated

Whether the cardholder name input field should be visible. This property is **deprecated**, set it on your Dashboard instead.

placeholderstring | (options: { locale: string }) => string

The placeholder text to display in the cardholder name input field. It can be either a string or a function that returns a string. The function receives an options object as first argument.

cardNumberobject

Customize the placeholder of the card number field.

Properties

placeholderstring | (options: { locale: string }) => string

The placeholder text to display in the cardholder number input field. It can be either a string or a function that returns a string. The function receives an options object as first argument.

expiryDateobject

Customize the placeholder of the expiry date field.

Properties

placeholderstring | (options: { locale: string }) => string

The placeholder text to display in the expiry date input field. It can be either a string or a function that returns a string. The function receives an options object as first argument.

cvvobject

Customize the placeholder of the CVV field.

Properties

placeholderstring | (options: { locale: string }) => string

The placeholder text to display in the CVV input field. It can be either a string or a function that returns a string. The function receives an options object as first argument.

preferredFlow"DEDICATED_SCENE" | "EMBEDDED_IN_HOME"

Specify the preferred flow for entering card details.

giftCardobject

Options for using gift cards as a payment method.

Properties

logoSrcstringRequired

The source URL of the button logo.

backgroundstringRequired

The background color of the button.

logoAltstring

An alternative text for the button logo.

textstring

The text to display on the button.

directDebitobject

Options for using direct debit as a payment method.

Properties

customerCountryCodestringRequired

The customer's two-letter country code.

companyNamestringRequired

The name of the company or organization accepting payments.

companyAddressstringRequired

The address of the company or organization accepting payments.

customerNamestring

The name of the customer making the payment.

customerEmailstring

The email address of the customer making the payment.

customerAddressLine1string

The first line of the customer's address.

customerAddressLine2string

The second line of the customer's address.

customerCitystring

The city of the customer's address.

customerPostalCodestring

The postal code of the customer's address.

ibanstring

The International Bank Account Number (IBAN) of the customer's bank account.

submitButtonLabelsobject

An object containing the text to display on the submit button for the Direct Debit form and mandate.

Properties

formstring | (options: { locale: string }) => string

The label to display on the submit button for the Direct Debit form.

mandatestring | (options: { locale: string }) => stringRequired

The label to display on the submit button for the Direct Debit mandate.

paypalobject

Options for using PayPal as a payment method.

Properties

buttonColor"gold" | "blue" | "silver" | "white" | "black"

The color of the PayPal button.

buttonShape"pill" | "rect"

The shape of the PayPal button.

buttonSize"small" | "medium" | "large" | "responsive"

The size of the PayPal button.

buttonHeightnumber

The height of the PayPal button, in pixels.

buttonLabel"checkout" | "credit" | "pay" | "buynow" | "paypal" | "installment"

The label displayed on the PayPal button.

buttonTaglineboolean

Whether to display the PayPal tagline beneath the button.

paymentFlow"DEFAULT" | "PREFER_VAULT"

The payment flow to use for the PayPal button.

onClick() => void

A function to be called when the PayPal button is clicked.

redirectobject

Options for payment methods that rely on redirecting.

Properties

returnUrlstring

The URL to return to after the redirect process has completed.

forceRedirectboolean

Whether to always use a redirect flow, rather than a popup window, even if other options are available. Default value is `false`.

googlePayobject

Options for using Google Pay as a payment method.

Properties

buttonType"long" | "short" | "book" | "buy" | "checkout" | "donate" | "order" | "pay" | "plain" | "subscribe"

buttonColor"default" | "black" | "white"

The color of the Google Pay button.

buttonSizeMode"fill" | "static"

The size mode of the Google Pay button.

onClick() => void

A function to be called when the Google Pay button is clicked.

captureBillingAddressboolean

Whether to prompt the user to select a billing address.

applePayobject

Options for using Apple Pay as a payment method.

Properties

buttonType"plain" | "buy" | "set-up" | "donate" | "check-out" | "book" | "subscribe"

The type of the Apple Pay button to display.

buttonStyle"white" | "white-outline" | "black"

The style of the Apple Pay button.

captureBillingAddressboolean

Whether to display a prompt for the user to enter their billing address during the payment process.

klarnaobject

Options for using Klarna as a payment method.

Properties

paymentFlow"DEFAULT" | "PREFER_VAULT"

The payment flow of the Klarna payment method.

recurringPaymentDescriptionstring

The description of the recurring payment.

allowedPaymentCategories("pay_now" | "pay_later" | "pay_over_time")[]

An array of string values that specify the allowed payment categories.

paymentHandling"AUTO" | "MANUAL"

Specify how payments should be handled.