Checkout SDK Configuration Reference: Init, Hosted Fields & 3-D Secure

This article describes the configuration options available for Checkout SDK, including top-level initialisation settings, configuration, field styling, and 3-D Secure challenge presentation. It also covers configuration defaults, parameter behaviour, and styling rules to help ensure a consistent and secure payment experience.

CheckoutInitConfig: top level

Parameter	Type	Default	Description
`apiKey` *	`string`	—	The account's public API key.
`merchantAccountId` *	`string`	—	The Merchant account identifier.
`paymentRequestId` *	`string`	—	The identifier of the payment request (`pr_…`) created by your backend.
`baseUrl`	`string`	script origin (CDN) or `window.location.origin` (npm)	The single domain hosting the iframe fields, the bridge, and the Checkout API. Must be an absolute HTTP(S) URL. For npm integrations it is virtually always set explicitly.
`features`	`FeatureStatic[]`	`[]`	npm mode: feature statics (e.g. `[hpfFeature]`). Registration only makes a type available — an instance is created only by calling `initFeature(type)`. If the session configuration contains a type that is not registered, `init()` fails immediately. Not passed in CDN mode (the features are already in the bundle via `?features=`).
`featureOptions`	`object`	`{}`	Merchant-side feature settings layered over the backend configuration (the merchant wins). Read at the moment of `initFeature(type)`. The key is the feature type: `featureOptions.hpf` (see 7.2).
`challenge`	`ChallengeConfig`	`{ acsMode: 'redirect' }`	3DS challenge presentation (see 7.4). Applies only to the `acs_redirect` directive.
`timeout`	`number` (ms)	`30000`	Timeout for RPC calls to the bridge. A positive finite number.
`initTimeout`	`number` (ms)	`30000`	Timeout for the bridge handshake during `init()`. A positive finite number.

*required parameter. A missing or empty value → init() rejects with an invalid_config error.

FeatureOptions.hpf: card fields

Parameter	Type	Description
`style`	`CommonStyling`	The global base style for all fields. The per-field style is layered on top (wins on each individual property).
`fields`	`Record<FieldType, …>`	Individual field settings. Keys: `cardNumber`, `expiryDate`, `cvv`, `cardholderName`.
`fields.<type>.container`	`string \| HTMLElement`	A CSS selector or DOM element where the field's iframe is mounted. The container must exist in the DOM at the moment of `initFeature('hpf')`. If the backend configuration marks the field as `required`, a missing container for it is a feature initialisation error (`feature_error`).
`fields.<type>.style`	`CommonStyling`	The style of a specific field on top of the global one.
`fields.<type>.placeholder`	`string`	The field's placeholder. Recommended values: `1234 1234 1234 1234`, `MM/YY`, `CVC`, the name on the card.

📘
Field configuration cascade: the session's backend configuration (default styles/placeholders/required flags) → the global featureOptions.hpf.style → the per-field fields.

CommonStyling: field style properties

A closed whitelist of 13 CSS properties (values are strings with CSS units). Other properties are not accepted due to a deliberate security restriction of Hosted Fields.

Property	Purpose
`height`	Field height (e.g. `'44px'`).
`width`	Field width.
`fontSize`	Font size (e.g. `'16px'`; on iOS ≥16px prevents auto-zoom).
`fontFamily`	Font family (the font must be available inside the iframe — web-safe or a system font).
`lineHeight`	Line height.
`letterSpacing`	Letter spacing.
`background`	Field background (transparent by default — inherits your container's design).
`color`	The color of the entered text.
`placeholderColor`	Placeholder color.
`paddingTop` / `paddingBottom` / `paddingLeft` / `paddingRight`	Inner padding. The field is a "bare" `<input>` inside an iframe with no UA padding; without padding the text will press against your container's border. Recommended starting point: `10px 12px`.

Challenge: 3-D Secure presentation

Applies only to the acs_redirect directive (the 3-DS challenge of both protocol versions). The redirect directive (APM / hosted pages) is always executed as a full-page navigation regardless of these settings.

Parameter	Type	Description
`acsMode`	`'redirect' \| 'iframe'`	Default: `'redirect'` — `redirect`: a full-page POST to the ACS in the current tab; the customer comes back via the payment request's `return_url`; the page reloads, and a fresh `init()` picks up the in-flight payment by itself. `iframe`: the challenge opens in an iframe inside the SDK's modal on top of your page (or in your own container). There is no navigation: the SDK instance, polling, and all mounted fields survive the challenge.
`container`	`string \| HTMLElement`	Only for `acsMode: 'iframe'`: mount the challenge iframe directly into your node — the SDK renders neither a backdrop nor a modal, it only adds/removes a single `<iframe>` (sibling elements are untouched). Your container defines the size (the iframe takes `100% × 100%`). The selector is resolved at the moment the challenge opens, not at `init()`. If resolution fails — a log entry + an error event (`invalid_config`, `details.challengeContainer`) and a fallback to the SDK modal.
`styles`	`ChallengeStyles`	Inline overrides on top of the SDK defaults, per node: `overlay` (the dimmed backdrop; modal mode only), `container` (the white modal "card" — fullscreen by default; set width / height for a windowed modal), `iframe` (the frame itself; applies in both modes). Value rules — below.
`classNames`	`ChallengeClassNames`	Additional CSS classes for the same nodes (`overlay` / `container` / `iframe`) — so you can style the challenge from your own stylesheet. Multiple classes separated by spaces. The SDK sets no classes of its own and never replaces yours. In container mode only `iframe` applies.

Styles value rules

The format is Record<cssProperty, value>; both spellings of a property are accepted (backgroundColor and background-color).
!important in a value is honoured: {zIndex: '10 !important'} is the only way to override an !important rule of your own stylesheet.
An empty string removes the property (that is how you strip an SDK default, e.g. the backdrop dimming), rather than setting an empty value.
All styles are applied inline on the nodes created by the SDK; no
For overlay: the SDK rewrites width / height / top / left on every viewport change; overriding one of them hands that property over to you (the rest keep tracking the viewport).