Configuration Object
const form = new Checkout(sessionId, options);
| Argument | Type | Description |
|---|---|---|
sessionId | string | Required. The id returned by POST /api/v1.0/sessions, obtained by your backend |
options | object | Optional. 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
| Option | Type | Default | What it does |
|---|---|---|---|
selector | 'auto' | 'always' | 'never' | 'auto' | When to show the payment method list |
theme | object | — | The component's look. See theme |
errorDisplay | 'none' | 'inline' | 'none' | Whether the component draws the BFF error message itself |
collectEmail | boolean | false | Whether 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
| Method | Description |
|---|---|
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.
| Value | Behaviour |
|---|---|
'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
| Key | Values | What it sets |
|---|---|---|
brandColor | color | Buttons, the selected state and the focus ring |
brandTextColor | color | Text on top of the brand color. Picked automatically when omitted |
textPrimaryColor | color | Primary text |
textSecondaryColor | color | Labels and descriptions. Derived from the primary text when omitted |
surfaceColor | color | The background. 'transparent' by default, so your page shows through |
borderColor | color | Field and container borders |
errorColor | color | Error borders and validation messages |
googleFont | a Google Fonts family name, e.g. 'Barlow' | The typeface. The component loads it inside its frames. See Fonts |
fontFamily | CSS font stack | The fallback while googleFont loads or if it fails, and the typeface when there is no googleFont |
fontSizeBase | e.g. '14px' | Labels and texts; the rest of the scale follows |
inputFontSize | e.g. '16px' | What the buyer types, in every field. Defaults to fontSizeBase + 2px. See Field text size |
borderRadius | e.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 |
inputTextTransform | any CSS text-transform | Applies to what the buyer types |
colorScheme | 'light', 'dark', 'system' | Default 'light'. 'system' follows the operating system and reacts when it changes |
dark | object | The 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.
| Value | Behaviour |
|---|---|
'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.