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.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.
Session, card token and payment method. See
ThreeDSAuthenticateContext.Promise<ThreeDSResult> — The terminal status and the 3DS ref for authorization.
Throws:
urn:radiumone:elements:three-ds:invalid-context(validation_error) —ctxis not an object.urn:radiumone:elements:three-ds:missing-session-id(validation_error) —sessionIdmissing or empty.urn:radiumone:elements:three-ds:missing-session-secret(validation_error) —sessionSecretmissing or empty.urn:radiumone:elements:three-ds:missing-card-token(validation_error) —cardTokenmissing or empty.urn:radiumone:elements:three-ds:missing-payment-method(validation_error) —selectedPaymentMethodmissing, empty or over 32 characters.urn:radiumone:elements:three-ds:invalid-purpose(validation_error) —purposeis set to something other than'payment'or'non_payment'.urn:radiumone:elements:three-ds:in-progress(rate_limited) — a flow is already running on this instance.urn:radiumone:elements:three-ds:cancelled(validation_error) — retryable —opts.signalwas aborted.urn:radiumone:elements:three-ds:challenge-timeout(network_error) — retryable — no terminal status before the deadline.urn:radiumone:elements:three-ds:provider-unavailable(network_error) — the gateway was unreachable or returned a malformed response.urn:radiumone:elements:three-ds:action-not-found(api_error) — 404 for the action reference.urn:radiumone:elements:three-ds:unsupported-action(validation_error) — unknown action type; update the SDK.urn:radiumone:elements:three-ds:action-malformed(validation_error) — the gateway action is missing required fields or carries an unknown status.urn:radiumone:elements:three-ds:render-mode-unsupported(validation_error) — the gateway sent a gateway-hosted challenge.urn:radiumone:elements:three-ds:challenge-display-unsupported(load_error) — redirect requested but not possible.urn:radiumone:elements:three-ds:http-<status>(api_error) — gateway HTTP error without a URN; retryable when status is 5xx.urn:radiumone:payment-gateway:*(api_error) — gateway error, passed through verbatim withretryAllowed.
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.
Returns Promise<ThreeDSResult> — The terminal status and the 3DS ref for authorization.
Throws:
urn:radiumone:elements:three-ds:invalid-action(validation_error) —actionis not an object with a stringtype.urn:radiumone:elements:three-ds:in-progress(rate_limited) — a flow is already running on this instance.ElementsErrorurn:radiumone:elements:three-ds:*and gateway URNs — as forThreeDS.authenticate.
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):
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:
urn:radiumone:elements:three-ds:action-malformed(validation_error) — no pending redirect, or the gateway returned an unknown status.urn:radiumone:elements:three-ds:challenge-timeout(network_error) — retryable — no terminal status within 30 seconds; callresume()again later.ElementsErrorurn:radiumone:elements:three-ds:provider-unavailable,urn:radiumone:elements:three-ds:action-not-found, gateway URNs — as forThreeDS.authenticate.
ThreeDSResult
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.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 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.
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.ISO 8601 upper bound for this action. Required on
decoupled actions. The SDK never waits past 5 minutes, even when this is later.Device data collection step. Present on
method actions.Status poll interval in milliseconds for
challenge and decoupled actions. Values below 1000 are raised to 1000.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'.Outcome. Required on terminal action types; a terminal action without a valid status rejects with
urn:radiumone:elements:three-ds:action-malformed.ThreeDSBrowserData
Collected automatically by authenticate() — exported for reference, not something you construct.
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.