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
- The browser leaves your page in a top-level form submission to the issuer’s authentication page.
- The shopper completes the challenge there.
- 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. - 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. - 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.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.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.
Decoupled authentication
Some issuers authenticate out-of-band — for example, the shopper approves the payment in their banking app instead of typing a code. PassonDecoupled to
show your own waiting UI:
expires_at or 5 minutes, whichever is sooner, then resolves EXPIRED.
Cancellation
Pass anAbortSignal to let the shopper cancel a challenge in progress (for
example with a “Cancel” button):
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, setchallengePresentation: "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
Next steps
Authentication results
Status meanings and 3DS error remedies.
Content Security Policy
CSP directives for card fields, 3DS iframes and redirects.