Skip to main content
ThreeDS coordinates 3D Secure from the browser after a card is tokenized. Get one from radiumone.threeDS(). One flow runs at a time per instance — a concurrent call throws urn:radiumone:elements:three-ds:in-progress; use a separate instance for parallel flows.
Never use a secret key (r1sk_…) in browser code, mobile apps, or anywhere a shopper can inspect it. Secret keys belong on your server only.
For the full integration walkthrough (session amount pinning, challenge presentation, results), see 3D Secure with Elements.
Your server’s API calls. Elements pages write them as the full path on the API host, as the SDK publishes them — for example, POST /gateway/v1/sessions is https://api.radiumone.io/gateway/v1/sessions (sandbox: https://api-sandbox.radiumone.io/gateway/v1/sessions). The Payments API reference lists the same operations relative to that base URL: POST /v1/sessions, PATCH /v1/sessions/{session_id}, GET /v1/payment-methods, POST /v1/transactions/purchase.

authenticate(context, options?)

Run 3D Secure for a bound card, from start to a terminal outcome, in one call. Collects browser data, calls POST /gateway/v1/3ds/authenticate, then performs whatever the gateway asks (device data collection, challenge, decoupled approval), polling GET /gateway/v1/3ds/status until a terminal status. Challenge and decoupled waits are capped at 5 minutes, even when the gateway allows longer: a challenge still open at 5 minutes rejects with challenge-timeout, a decoupled approval resolves EXPIRED. No amount or currency is sent — the gateway takes them from the session. Only one flow may run per instance. Error codes: SDK codes are urn:radiumone:elements:three-ds:*; those with type: 'validation_error' before any network call mean the call was constructed wrong. Gateway error URNs are passed through verbatim. Full catalogue: the Elements error reference.
ThreeDSAuthenticateContext
required
Session, card token and payment method. See ThreeDSAuthenticateContext.
ThreeDSHandleOptions
Presentation, cancellation and decoupled-UI options.
Returns Promise<ThreeDSResult> — The terminal status and the 3DS ref for authorization. Throws:

handle(action, options?)

Drive a gateway 3DS action (obtained by your server) to a terminal outcome. Same flow and errors as ThreeDS.authenticate, minus the initial authenticate call and its argument checks. Pass the action unchanged: it is the data member of the gateway’s success response {status: "ok", data, request_id}, never the whole response.
ThreeDSAction
required
The gateway action. See ThreeDSAction.
ThreeDSHandleOptions
Presentation, cancellation and decoupled-UI options.
Returns Promise<ThreeDSResult> — The terminal status and the 3DS ref for authorization. Throws:

getPendingRedirect()

Detect whether this page load is the return from a redirect challenge. Reads the pending reference from sessionStorage, then from the action_ref URL query or fragment parameter. Call at the top of your return page. Returns PendingRedirect | null — The pending redirect, or null if this is not a 3DS return. PendingRedirect (the returned value):
string
required
The in-flight 3DS action reference being resumed.

resume()

Finish a redirect challenge on the return page. Needs only the publishable key: reads the pending reference (see ThreeDS.getPendingRedirect) and polls the status for up to 30 seconds, since the issuer’s result can land just after the shopper does. Safe to call again: on a timeout the pending reference is kept, so a reload can resume. No card Elements or session secret are required. Returns Promise<ThreeDSResult> — The terminal status and the 3DS ref. Throws:

ThreeDSResult

number
Issuer challenges (including decoupled approvals) this card may still receive for purpose: 'non_payment' in this checkout session, as of the gateway response that produced this result (0 up to the gateway’s cap, 3 by default; passed through unchanged). A frictionless authentication does not use one, and a successful authentication restores the cap. Present only when that final response carries it, which the gateway does for purpose: 'non_payment' only; undefined for payments, a decoupled EXPIRED, or a gateway that does not send it. At 0, the next non-payment authenticate() for this card rejects with urn:radiumone:payment-gateway:three-ds:card-attempts-exceeded.
string
required
3DS reference to pass to your server’s purchase or authorization call, for a payment authentication only. A purpose: 'non_payment' reference is never sent anywhere.
ThreeDSStatus
required
Terminal status — never DECOUPLED or PENDING. See ThreeDSStatus.
ThreeDSStatus values: AUTHENTICATED, ATTEMPTED, NOT_AUTHENTICATED, FAILED, REJECTED, DECOUPLED, EXPIRED, PENDING

ThreeDSAction

For integrations that obtain the first 3DS action server-side and pass it to handle() unchanged — most integrations never touch this shape directly.
string
required
Gateway reference for this action; used for continue and status calls.
number
Issuer challenges this card may still receive for purpose: 'non_payment' in this checkout session, as of this response; sent for non-payment authentications only. The SDK surfaces it as ThreeDSResult.cardAttemptsRemaining from the response that resolves the flow, never from an intermediate action; a value that is not a non-negative integer is ignored.
{ acs_url: string; fields: Record<string, string>; window_size?: string; notification_ref?: string; redirectable?: boolean; }
Issuer challenge step. Present on challenge actions.
string
ISO 8601 upper bound for this action. Required on decoupled actions. The SDK never waits past 5 minutes, even when this is later.
{ url: string; }
Hosted challenge URL for gateway_hosted render mode. Not supported yet.
{ url: string; fields: Record<string, string>; timeout_ms?: number; }
Device data collection step. Present on method actions.
number
default:"5000 for challenge, 3000 for decoupled"
Status poll interval in milliseconds for challenge and decoupled actions. Values below 1000 are raised to 1000.
boolean
Gateway hint that the browser handles a full-page redirect better than an iframe (for example an in-app webview). Honoured when challengePresentation is 'auto'.
ThreeDSRenderMode
Challenge rendering mode. Present on challenge actions.
ThreeDSStatus
Outcome. Required on terminal action types; a terminal action without a valid status rejects with urn:radiumone:elements:three-ds:action-malformed.
ThreeDSActionType
required
What the SDK must do next. See ThreeDSActionType.

ThreeDSBrowserData

Collected automatically by authenticate() — exported for reference, not something you construct.
number
required
screen.colorDepth.
boolean
required
navigator.javaEnabled(); false when unavailable.
boolean
required
Always true.
string
required
navigator.language (BCP 47 tag).
number
required
screen.height in CSS pixels.
number
required
screen.width in CSS pixels.
number
required
UTC offset in minutes, from Date#getTimezoneOffset() — positive when behind UTC, so UTC+8 is -480.

Example

handle() and collectBrowserData() are for integrations whose own server starts the authentication. Most integrations only need authenticate(); contact support before you build on handle().

Gateway calls

The SDK makes these gateway HTTP calls on your behalf — bind runs from elements.submit(), the rest from authenticate()/handle()/resume(). You don’t call these directly; this is for troubleshooting with network traces or support. Base URL is the API origin for the key’s environment (production api.radiumone.io, sandbox api-sandbox.radiumone.io) — see Content Security Policy.

Errors

The SDK’s 3DS error codes (urn:radiumone:elements:three-ds:*) and the gateway codes it passes through (urn:radiumone:payment-gateway:*) are documented on 3D Secure errors. Status-outcome tables (what each status means and whether to authorize) live on Authentication results. For recovery steps, see Handle 3D Secure failures in Elements.
Last modified on October 25, 2026