ThreeDSChallengeOptions
Options for threeDSChallenge.
Extends
Properties
acsUrl?
optional acsUrl?: string;
EMVCo alias for url — the issuer ACS challenge endpoint from the authentication response.
challengeData?
optional challengeData?: string;
The opaque challenge_data blob from the POST /v2/payments answer, forwarded verbatim.
Supplies acsUrl, creq and challengeWindowSize. Explicit options override it, except the
window size: the blob's value is the one the AReq announced, so it wins.
challengeWindowSize?
optional challengeWindowSize?: "01" | "02" | "03" | "04" | "05";
Iframe size, as the EMVCo code, for a call that carries no challengeData. Defaults to 05
(fills the container).
The size is an AReq echo, not a client-side choice — EMVCo requires the rendered frame to match
what was announced — so a challengeWindowSize inside the blob wins over this one.
completion?
optional completion?: ThreeDSCompletion;
How the ACS reports that the cardholder is done. Required unless resolveAfterLoads is set —
a challenge has no other way to report a result.
Overrides
ThreeDSFrameOptionsBase.completion
container
container: string | HTMLElement;
Where the challenge is rendered: an element id or the element itself. Required — the challenge is shown in-context, in a slot your checkout controls, and the SDK adds no overlay of its own.
creq?
optional creq?: string;
EMVCo alias for fields — posted as a single creq field.
fields?
optional fields?: Record<string, string>;
Form fields to post, one hidden input per entry.
Inherited from
ThreeDSFrameOptionsBase.fields
frameName?
optional frameName?: string;
name and id given to the iframe. Defaults to a unique per-call name; set it only if you need
to find the frame yourself.
Inherited from
ThreeDSFrameOptionsBase.frameName
keepFrame?
optional keepFrame?: boolean;
Keeps the iframe and its form in the DOM after settling. Off by default — leaving 3DS frames behind is what leaks memory across retries.
Inherited from
ThreeDSFrameOptionsBase.keepFrame
onLoad?
optional onLoad?: () => void;
Called on each navigation of the challenge iframe — a timing signal, useful to swap a spinner for the frame. It carries no outcome.
Returns
void
resolveAfterLoads?
optional resolveAfterLoads?: number;
Settle after this many navigations of the iframe instead of on a message.
For a provider whose result page is a plain navigation rather than a postMessage, this is the
only signal there is — the Purse 3DS challenge posts one, so use completion there. The
about:blank document the iframe starts on is not counted, so 1 means the first real
navigation. Can be combined with completion: whichever fires first settles the challenge.
signal?
optional signal?: AbortSignal;
Aborts the flow: the iframe is torn down and the promise resolves with status: 'aborted'.
Inherited from
ThreeDSFrameOptionsBase.signal
timeoutMs?
optional timeoutMs?: number;
Hard stop, in milliseconds. Defaults to 600_000 (10 min) — long enough for an OTP or a banking
app confirmation, short enough that a silent ACS eventually releases the checkout.
title?
optional title?: string;
Accessible name of the challenge iframe, e.g. in the checkout's language. Defaults to
'3D Secure authentication'.
url?
optional url?: string;
Endpoint the form is posted to. Must be http: or https:.