ThreeDS object - Elements SDK

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 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.

`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. Waits are capped at 5 minutes. No amount or currency is sent — the gateway takes them from the session. Only one flow may run per instance. Error codes: the three-ds:* codes below mean the call was constructed wrong. The urn:radiumone:three-ds:* codes are flow failures to handle at runtime; gateway error URNs are passed through verbatim. Full catalogue: docs/reference/error-codes.json.

ThreeDSAuthenticateContext

required

Session and card token. See ThreeDSAuthenticateContext.

Hide ThreeDSAuthenticateContext properties

string

required

BindResult.token from a successful Elements.submit.

string

required

session_id from POST /gateway/v1/sessions — the same session used for submit().

string

required

session_secret for the same session. Held in memory for the call only.

ThreeDSHandleOptions

Presentation, cancellation and decoupled-UI options.

Hide ThreeDSHandleOptions properties

HTMLElement | string

Element or CSS selector where the challenge iframe (or the decoupled waiting UI) mounts.

'auto' | 'iframe' | 'redirect'

default:"'auto'"

How to present a challenge.

'auto' — iframe, unless the gateway’s prefer_redirect hint asks for redirect. - 'iframe' — always an embedded iframe. - 'redirect' — always a full-page redirect; requires returnUrl and a challenge that is redirectable (or carries prefer_redirect), otherwise rejects with urn:radiumone:three-ds:challenge-display-unsupported.

On the redirect path the page navigates away, so the pending promise never settles; the return page completes the flow with ThreeDS.resume.

(info: { expires_at: string; poll_interval_ms: number; }) => void

Called once when a decoupled (out-of-band) approval starts, so you can show your own countdown or cancel UI. The SDK still runs the status polling.

string

Your 3DS return page. Setting it enables the redirect path; the page must load the SDK and call ThreeDS.resume.The SDK does not send this value to the gateway — the gateway redirects the shopper to the return URL configured for your merchant account, which must match.

AbortSignal

Abort the flow (for example when the shopper closes your payment panel). Aborting tears down all 3DS UI and rejects with urn:radiumone:three-ds:cancelled. Do not authorize after a cancellation.

Returns Promise<ThreeDSResult> — The terminal status and the 3DS ref for authorization. Throws:

three-ds:invalid_context (validation_error) — ctx is not an object.
three-ds:missing_session_id (validation_error) — sessionId missing or empty.
three-ds:missing_session_secret (validation_error) — sessionSecret missing or empty.
three-ds:missing_card_token (validation_error) — cardToken missing or empty.
three-ds:in_progress (rate_limited) — a flow is already running on this instance.
urn:radiumone:three-ds:cancelled (validation_error) — retryable — opts.signal was aborted.
urn:radiumone:three-ds:challenge-timeout (network_error) — retryable — no terminal status before the deadline.
urn:radiumone:three-ds:provider-unavailable (network_error) — the gateway was unreachable or returned a malformed response.
urn:radiumone:three-ds:action-not-found (api_error) — 404 for the action reference.
urn:radiumone:three-ds:unsupported-action (validation_error) — unknown action type; update the SDK.
urn:radiumone:three-ds:action-malformed (validation_error) — the gateway action is missing required fields.
urn:radiumone:three-ds:render-mode-unsupported (validation_error) — the gateway sent a gateway-hosted challenge.
urn:radiumone:three-ds:challenge-display-unsupported (load_error) — redirect requested but not possible.
urn:radiumone:three-ds:http-<status> (api_error) — gateway HTTP error without a URN; retryable when status is 5xx.
urn:radiumone:* (api_error) — gateway error, passed through verbatim with retryAllowed.

`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 gateway action object unchanged.

ThreeDSAction

required

The gateway action. See ThreeDSAction.

ThreeDSHandleOptions

Presentation, cancellation and decoupled-UI options.

Hide ThreeDSHandleOptions properties

HTMLElement | string

Element or CSS selector where the challenge iframe (or the decoupled waiting UI) mounts.

'auto' | 'iframe' | 'redirect'

default:"'auto'"

How to present a challenge.

'auto' — iframe, unless the gateway’s prefer_redirect hint asks for redirect. - 'iframe' — always an embedded iframe. - 'redirect' — always a full-page redirect; requires returnUrl and a challenge that is redirectable (or carries prefer_redirect), otherwise rejects with urn:radiumone:three-ds:challenge-display-unsupported.

On the redirect path the page navigates away, so the pending promise never settles; the return page completes the flow with ThreeDS.resume.

(info: { expires_at: string; poll_interval_ms: number; }) => void

Called once when a decoupled (out-of-band) approval starts, so you can show your own countdown or cancel UI. The SDK still runs the status polling.

string

AbortSignal

Abort the flow (for example when the shopper closes your payment panel). Aborting tears down all 3DS UI and rejects with urn:radiumone:three-ds:cancelled. Do not authorize after a cancellation.

Returns Promise<ThreeDSResult> — The terminal status and the 3DS ref for authorization. Throws:

three-ds:invalid_action (validation_error) — action is not an object with a string type.
three-ds:in_progress (rate_limited) — a flow is already running on this instance.
ElementsError urn:radiumone:three-ds:* and gateway URNs — as for ThreeDS.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):

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 fetches the final status once. Safe to call again. No card Elements or session secret are required. Returns Promise<ThreeDSResult> — The terminal status and the 3DS ref. Throws:

urn:radiumone:three-ds:action-malformed (validation_error) — no pending redirect, or the status is not terminal yet.
ElementsError urn:radiumone:three-ds:provider-unavailable, urn:radiumone:three-ds:action-not-found, gateway URNs — as for ThreeDS.authenticate.

`ThreeDSResult`

string

required

3DS reference to pass to your server’s authorization call.

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.

{ acs_url: string; fields: Record<string, string>; window_size?: string; notification_ref: string; redirectable?: boolean; }

Issuer challenge step. Present on challenge actions.

Show challenge shape

string

required

Record<string, string>

required

string

required

boolean

{ expires_at: string; poll_interval_ms?: number; }

Out-of-band approval step. Present on decoupled actions.

Show decoupled shape

string

required

number

{ url: string; }

Hosted challenge URL for gateway_hosted render mode. Not supported yet.

Show hosted shape

string

required

{ url: string; fields: Record<string, string>; timeout_ms?: number; }

Device data collection step. Present on method actions.

Show method shape

string

required

Record<string, string>

required

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: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

const threeDS = radiumone.threeDS();
const controller = new AbortController();

const { status, ref } = await threeDS.authenticate(
  { sessionId, sessionSecret, cardToken: token },
  {
    signal: controller.signal,
    challengeContainer: "#three-ds",
    returnUrl: "https://shop.example.com/checkout/3ds-return",
  },
);

if (status === "AUTHENTICATED" || status === "ATTEMPTED") {
  await chargeWithThreeDsRef(token, ref);
} else {
  showDeclined(status); // resolved decline — do not charge
}

// Return page (redirect fallback)
const pending = RadiumOne.init("r1pk_test_YOUR_KEY").threeDS().getPendingRedirect();
if (pending) {
  const { status, ref } = await radiumone.threeDS().resume();
  // same branch as above
}

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.

Call	Method + path	Called from	SDK API(s)	Notes
`bind`	`POST /gateway/v1/sessions/{session_id}/bind`	`card iframe (origin {cdnOrigin})`	`Elements.submit`	15s timeout. Up to 2 retries (1 s, 2 s backoff) when retry_allowed is true or no HTTP response was received.
`3ds-authenticate`	`POST /gateway/v1/3ds/authenticate`	`merchant page`	`ThreeDS.authenticate`	Body: `{ session_id, card, browser } — no amount or currency`.
`3ds-continue`	`POST /gateway/v1/3ds/continue`	`merchant page`	`ThreeDS.authenticate`, `ThreeDS.handle`	Body: `{ action_ref }`.
`3ds-status`	`GET /gateway/v1/3ds/status/{action_ref}`	`merchant page`	`ThreeDS.authenticate`, `ThreeDS.handle`, `ThreeDS.resume`	Every poll_interval_ms (default 5000 challenge, 3000 decoupled, minimum 1000), up to 5 minutes.

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

3DS-specific error codes (three-ds:*) and gateway URNs 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.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

ThreeDS object - Elements SDK

`authenticate(context, options?)`

`handle(action, options?)`

`getPendingRedirect()`

`resume()`

`ThreeDSResult`

`ThreeDSAction`

`ThreeDSBrowserData`

Example

Gateway calls

Errors

​authenticate(context, options?)

​handle(action, options?)

​getPendingRedirect()

​resume()

​ThreeDSResult

​ThreeDSAction

​ThreeDSBrowserData

​Example

​Gateway calls

​Errors

`authenticate(context, options?)`

`handle(action, options?)`

`getPendingRedirect()`

`resume()`

`ThreeDSResult`

`ThreeDSAction`

`ThreeDSBrowserData`

Example

Gateway calls

Errors