Skip to main content

Configuration Object

const form = new Checkout(sessionId, options);
ArgumentTypeDescription
sessionIdstringRequired. The id returned by POST /api/v1.0/sessions, obtained by your backend
optionsobjectOptional. Everything below

The amount is not passed here. It is fixed when your backend creates the session, so it cannot be changed from the browser.

All options​

OptionTypeDefaultWhat it does
selector'auto' | 'always' | 'never''auto'When to show the payment method list
themeobject—The component's look. See theme
errorDisplay'none' | 'inline''none'Whether the component draws the BFF error message itself
collectEmailbooleanfalseWhether the form asks the buyer for an email
onReady() => void—Lifecycle hook
onSubmit({ module, result? }) => void | Promise<void>—Lifecycle hook
onError(error: CheckoutError) => void—Lifecycle hook
onAmountChange(amount: number | null) => void—Lifecycle hook
onBinChange(info | null) => void—Lifecycle hook
onModuleEvent({ module, name, data? }) => void—Lifecycle hook

All of them are optional. Everything not listed here is not part of the contract: the component reads its operational data — public key, card brands, enabled payment methods and all buyer-facing copy — from the BFF, never from your page.

Methods​

MethodDescription
render(target)Mounts the component. target is a container id or the element itself. Returns a promise
unmount()Tears it down. Idempotent — calling it twice is not an error
setTheme(theme)Replaces the theme, mounted or not. See Changing the theme after mount

selector​

Controls when the payment method list is shown.

ValueBehaviour
'auto' (default)Lists when more than one method is enabled; mounts directly when there is only one
'always'Always lists, even with a single method enabled
'never'Never lists: mounts the first method the merchant has enabled

'never' exists for checkouts that already have their own payment method selector outside the component. With more than one method enabled it leaves the others unreachable, since there is currently no way to tell render() which one to mount.

Which methods exist at all is decided by the merchant's configuration on the BFF, not by your snippet — so enabling a new payment method does not require touching your integration.

theme​

Set a handful of values and the component matches your checkout. You do not style it with CSS: the fields live in isolated frames your stylesheets cannot reach, so the look is configured through these keys instead.

theme: {
brandColor: '#7C3AED',
textPrimaryColor: '#1C1917',
surfaceColor: 'transparent',
borderColor: '#D6D3D1',
errorColor: '#DC2626',

googleFont: 'Barlow',
fontFamily: 'Inter, system-ui, sans-serif',
fontSizeBase: '14px',
inputFontSize: '16px',
borderRadius: '8px',

inputStyle: 'underline',
labelStyle: 'stacked',
buttonShape: 'rounded',
density: 'comfortable',

colorScheme: 'system',
dark: { surfaceColor: '#0B0B0F' },
}

Every key is optional. Anything you leave out keeps a sensible default, and the values you do set carry further than the field they name — set the brand color and the buttons, the selected state and the focus ring all follow it. Do not pass an empty string to remove something: leave the key out instead.

Keys​

KeyValuesWhat it sets
brandColorcolorButtons, the selected state and the focus ring
brandTextColorcolorText on top of the brand color. Picked automatically when omitted
textPrimaryColorcolorPrimary text
textSecondaryColorcolorLabels and descriptions. Derived from the primary text when omitted
surfaceColorcolorThe background. 'transparent' by default, so your page shows through
borderColorcolorField and container borders
errorColorcolorError borders and validation messages
googleFonta Google Fonts family name, e.g. 'Barlow'The typeface. The component loads it inside its frames. See Fonts
fontFamilyCSS font stackThe fallback while googleFont loads or if it fails, and the typeface when there is no googleFont
fontSizeBasee.g. '14px'Labels and texts; the rest of the scale follows
inputFontSizee.g. '16px'What the buyer types, in every field. Defaults to fontSizeBase + 2px. See Field text size
borderRadiuse.g. '8px'Base corner radius; the rest of the scale follows
density'compact', 'comfortable'Field height and spacing. 'compact' fits a modal or a narrow column
inputStyle'outlined', 'underline', 'filled'How a field is drawn
labelStyle'stacked', 'floating'Default 'stacked', the label above the field. See Floating labels
buttonShape'rounded', 'pill'How a button is drawn
inputTextTransformany CSS text-transformApplies to what the buyer types
colorScheme'light', 'dark', 'system'Default 'light'. 'system' follows the operating system and reacts when it changes
darkobjectThe colors for dark mode. Takes the same color keys; it reuses your brand color, so you only set what differs

The same theme applies everywhere the component draws: the payment method list, the form and the fields. A checkout where those look different is not something the component can produce, and that is on purpose.

Fonts​

The form lives in iframes, so a font your page loads does not reach it. To use a Google Fonts typeface, pass its name in googleFont and the component loads it in each of its frames; fontFamily is used while it loads, or if it does not.

Only Google Fonts, and only by name: there is no way to pass a font URL. The component's frames do not load fonts from any other host, which keeps a font from being used to tell what the buyer types. A name that is not a plain family name (letters, digits and spaces) is ignored. With any other fontFamily, the browser uses the font only if it is installed on the buyer's device.

Field text size​

inputFontSize is the size of what the buyer types, the same in all fields; the placeholder follows it. Safari on iOS zooms in when a field under 16px gets focus, so with fontSizeBase: '14px' keep it at '16px', which is exactly the default.

Floating labels​

With labelStyle: 'floating' each field's name sits inside it, where the text goes, and moves up when the field gets focus or has a value; the placeholder shows only while the field has focus. All fields grow so the label and the text fit: 52px, or 46px with density: 'compact'.

Changing the theme after mount​

form.setTheme({ brandColor: '#7C3AED', colorScheme: 'dark' });

It replaces the whole theme, it does not merge it: merging would leave no way to remove a color, and you already have the object you passed to the constructor. Calling it with nothing mounted is not an error either — the theme is stored and used by the next render().

To follow the system dark mode you do not need to call it at all: with colorScheme: 'system' the component subscribes itself and reacts when the OS changes.

errorDisplay​

Whether the component draws the BFF's error message inside its own iframe.

ValueBehaviour
'none' (default)The component does not draw it. The error reaches onError with a userMessage ready to show, and you decide where it goes
'inline'The component draws it below the button, in addition to calling onError

'none' is the default on purpose: the buyer-facing message normally belongs next to the rest of your checkout's messages, not inside an iframe you do not control. Use 'inline' while your integration does not handle onError yet — without it the buyer presses Pay and sees nothing.

Two things the component always draws, regardless of this option, because they cannot live outside: per-field validation errors, which sit next to their input inside the iframe, and the panel that replaces the form when the session dies. Both also reach onError.

collectEmail​

Whether the form asks the buyer for an email address. Off by default.

When on, the field appears, is required to pay, and the email travels with the payment intent. When off the field does not exist: it is not drawn, not validated and not sent.

You can enable it in any checkout mode. If you leave it off (default), Hybrid/Complete still expect the cardholder email on POST /payment (with X-Session-Id) from your backend, as described in Backend Integration. The mode itself is fixed when your backend creates the session, not by this snippet.

Buyer-facing texts are configured by the merchant​

There is no way to pass texts from the snippet, and that is deliberate. Labels, placeholders, error messages, the save-card consent and the bot-protection notice all come from GET /config (header X-Session-Id), which returns whatever the merchant has configured for their tenant.

The component has no texts of its own. If one is missing from the configuration, the form does not mount: onError receives CONFIG_INVALID with every missing path in details.missing — for example modules[pci-card].labels.cardNumber.error — so it can be fixed in the tenant configuration.

The reason is that those texts belong to the merchant, not to whoever writes the page. They are configured once and hold for every integration that merchant has. With an override in the snippet, two pages of the same merchant could say different things, and the one in production was not necessarily the one somebody reviewed.

If you need a text changed, it is requested through the tenant configuration.