Skip to main content
Most 3DS authentications resolve frictionlessly with no shopper interaction. When the issuer requires a challenge, threeDS.authenticate() presents it in an iframe or modal by default. Where RadiumOne enables it, a challenge can instead run as a full-page redirect to the issuer’s page — this guide covers both.

Container vs. modal

By default, a challenge renders in a centered modal overlay (role="dialog", non-dismissable). To render it inline instead, pass challengeContainer:
challengeContainer accepts an element or a CSS selector. Use it when you want the challenge to appear inside your own checkout layout instead of a floating overlay.

Choosing how the challenge presents

challengePresentation controls whether a challenge uses an iframe or a full-page redirect: A challenge allows a redirect only where RadiumOne has turned redirect challenges on. Otherwise every challenge renders in an iframe, and redirect throws. Contact support if you need redirect challenges. Use redirect (or rely on auto with returnUrl set) inside in-app webviews, where a same-origin iframe challenge may not render reliably.
returnUrl must be {your checkout page origin}/3ds/return, for example https://shop.example.com/3ds/return. It only turns the redirect path on: the SDK doesn’t send it. RadiumOne builds the return address from the origin of the page that called authenticate() plus the fixed path /3ds/return, so serve your return page at exactly that path on your checkout origin.

How it works: the redirect path

  1. The browser leaves your page in a top-level form submission to the issuer’s authentication page.
  2. The shopper completes the challenge there.
  3. RadiumOne sends the shopper back to {your checkout origin}/3ds/return, with #action_ref= in the URL fragment. getPendingRedirect() also reads ?action_ref= if it’s ever in the query string.
  4. Your return page resumes the pending 3DS flow and reads the final status. resume() checks for up to 30 seconds, because the issuer’s result can land just after the shopper does.
  5. Your server charges using the resulting reference, same as the non-redirect path.

The return page

Serve the redirect return page with Referrer-Policy: no-referrer, and don’t load third-party scripts on it. The action_ref in the URL is a capability — anything that can read the URL or a Referer header sent from this page can look up the 3DS status.
If resume() rejects with urn:radiumone:elements:three-ds:challenge-timeout, the result isn’t final yet and the pending reference is kept: call resume() again (or reload the page) before you treat it as a failure, since the authentication may already have succeeded. A transport failure (urn:radiumone:elements:three-ds:provider-unavailable) also keeps it. urn:radiumone:elements:three-ds:action-not-found clears it: that reference can never resolve, so restart the payment.
Your checkout origin must be https:// and on your account’s allowed-origins list — contact support to add it. Otherwise RadiumOne doesn’t redirect back at all: the shopper finishes on a RadiumOne completion page, and your return page never loads.
Redirect and return routes need a slightly loosened Content Security Policy (form-action allowing https:) scoped to just those routes. The page that starts 3D Secure also needs the device-data origin in frame-src and form-action, whichever presentation you use — see Content Security Policy.
3DS calls run on your own checkout page, not a RadiumOne-hosted one — your CSP’s connect-src must include your API origin. Without it, the browser silently blocks the status calls and a challenge times out after 5 minutes instead of failing fast. See Content Security Policy: troubleshooting.

Decoupled authentication

Some issuers authenticate out-of-band — for example, the shopper approves the payment in their banking app instead of typing a code. Pass onDecoupled to show your own waiting UI:
The SDK polls the authentication status on your behalf until it reaches a final state or expires — you don’t need to poll yourself. It waits until expires_at or 5 minutes, whichever is sooner, then resolves EXPIRED.

Cancellation

Pass an AbortSignal to let the shopper cancel a challenge in progress (for example with a “Cancel” button):
A cancelled authentication rejects with urn:radiumone:elements:three-ds:cancelled. Return the shopper to the payment form — don’t retry automatically. See Handle 3D Secure failures in Elements for this and other rejected-flow cases.

In-app webviews

In-app browsers (for example inside a mobile app’s webview) don’t always support cross-origin iframes reliably. Where redirect challenges are enabled, set challengePresentation: "redirect" and serve the /3ds/return page on the same origin inside your webview.
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.

Server policy

Whichever presentation you use, your server must still independently validate the three_ds.ref at charge time — never trust a browser-reported status alone. See Server policy.

Next steps

Authentication results

Status meanings and 3DS error remedies.

Content Security Policy

CSP directives for card fields, 3DS iframes and redirects.
Last modified on October 25, 2026