How it works
- Your server creates a tokenization session and pins the net payable amount.
- The shopper enters their card; Elements tokenizes it (
elements.submit()). - The browser starts 3DS authentication (
threeDS.authenticate()), which may run frictionless or present a challenge. - Your server authorizes or purchases using the card token plus the 3DS reference. The gateway independently verifies the reference before it authorizes the charge.
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.Before you begin
Requires:
- 3D Secure enabled on your account.
- A CSP that allows the 3DS origins in
connect-src,frame-srcandform-action. Without the API origin inconnect-src, a challenge times out after 5 minutes instead of failing fast. See Content Security Policy. - A checkout page served over
https://from an origin on your account’s allowed-origins list. Contact support to add each origin that runs 3D Secure. - Elements SDK
v1.6.1or later.purposeandcollectBrowserData()needv1.6.4or later.
Steps
1
Create a payment session and pin the amount
Create a session with If the amount changes before the shopper pays (for example after they redeem
loyalty points), pin the new net payable amount before you call
See the
net_payable_amount, the amount 3DS will
authenticate. It must be the amount you’ll actually charge to the card. For a
plain card sale it equals amount. Add the cardholder’s billing details
if you hold them: issuers approve more payments without a challenge when they
get them (see Cardholder billing data).authenticate(). Changing it after an authentication cancels that
authentication, so authenticate again for the new amount.PATCH /gateway/v1/sessions/{session_id} reference
for the request and response, and the
ThreeDS reference for how this step fits
the browser-driven flow. Keep ttl_minutes at 30 or less for a 3DS
checkout — see Token lifetime below.2
Tokenize the card in the browser
3
Authenticate with 3D Secure
selectedPaymentMethod is required: the payment_methods[].type the
shopper chose, card for a card payment. Take it from the
payment_methods[] your server gets from
GET /gateway/v1/payment-methods,
or from the POST /gateway/v1/sessions response when you send a currency. The SDK
rejects a missing, empty or longer-than-32-character value locally with
urn:radiumone:elements:three-ds:missing-payment-method, before any
network call. The API rejects a value that isn’t offered for this checkout
with urn:radiumone:payment-gateway:checkout:payment-method-not-offered.A decline resolves, it doesn’t throw. See
Authentication results for every
status and its meaning, and for 3DS error remedies. Don’t call
authenticate() again in a loop after a 4xx error: every call counts
against the session’s 3DS attempt budget, even one that fails — see
Attempt budget.4
Charge with the 3DS reference on your server
Send the token and the 3DS
ref from the browser to your server, then
purchase or authorize with three_ds:{ref} (API reference).Verify the cardholder without a payment
To check that the shopper is the cardholder before any payment, for example before you show a rewards balance, passpurpose: "non_payment":
- The flow, the challenge UI and the statuses are the same as for a payment. An
issuer refusal resolves
FAILEDorREJECTED. An issuer that doesn’t support this kind of check resolvesNOT_AUTHENTICATED. Neither is an error. ATTEMPTEDmeans the cardholder wasn’t actually verified. There’s no liability shift without a payment, so accepting it is your own risk decision.- No amount is authenticated, so the session doesn’t need a
net_payable_amountfor this call. - The result is for your page only. Don’t send this
refto your server’s purchase or authorize call: it’s refused with422 urn:radiumone:payment-gateway:three-ds:ref-purpose-mismatch. - Treat it as a UX gate, not proof. The status lives in the browser. Never let your server grant value only because the page reports a verified cardholder.
- The payment still needs its own authentication. Pin the net payable amount,
then call
authenticate()again withoutpurposeand charge with that call’sref. Both calls count against the session’s attempt budget. Run them one after the other: overlapping calls on oneThreeDSinstance reject withurn:radiumone:elements:three-ds:in-progress. - A
purposeother than"payment"(the default) or"non_payment"rejects locally withurn:radiumone:elements:three-ds:invalid-purpose.
Limit per card
A non-payment authentication allows at most 3 issuer challenges per card in a checkout session. The limit protects the real cardholder from repeated prompts on their phone. It follows the card, so entering the same card again doesn’t reset it.
The result carries
cardAttemptsRemaining (Elements SDK 1.7.0 or later), a number
from 0 to 3 taken from the final response of the authentication:
undefined on a payment authentication and on a decoupled EXPIRED result, and it
can be missing on other results, so don’t treat a missing value as 0. A cancelled or
timed-out challenge uses an attempt but rejects instead of resolving, so there’s no result
to read. Use the count for your messaging, and always handle the refusal below.
At 0, the next non-payment authenticate() with that card rejects with
422 urn:radiumone:payment-gateway:three-ds:card-attempts-exceeded
(retryAllowed: false) without contacting the issuer. What you do next depends on the check:
- With
selectedPaymentMethod: "uob_irr", ask the shopper for a different card and switch to it. - With any other method, a different card on the same session is refused with
409 urn:radiumone:tokenization:session-not-bindable, so start a new session.
Switch to a different card (rewards only)
If the shopper needs another card for the rewards balance check, you can bind a different card to the same session. This works only while all of these hold:- A non-payment authentication has run on the session with
selectedPaymentMethodset to the rewards method (uob_irr) and 3D Secure could run for it. Passingpurpose: "non_payment"withselectedPaymentMethod: "card"doesn’t allow a switch. - No payment authentication has started on the session.
- The session hasn’t been used for a charge.
clear({ all: true }) on the combined card Element (or
clear() on each split Element), let the shopper enter the new card, and call
elements.submit() again. You get a new card token, and the previous token is revoked:
use only the new token from then on. A revoked token fails with
urn:radiumone:payment-gateway:three-ds:card-token-invalid. An earlier result belongs to the
previous card, so run the non-payment check again with the new token before you show its
balance.
A session accepts up to 3 cards, counting the first. Each change of card uses one, so
going from card A to card B and back to card A uses all 3. The next different card makes
elements.submit() reject with 409 urn:radiumone:tokenization:session-card-limit-reached. Nothing is charged, and only a new
session helps. A card that has already spent its 3 attempts stays refused after a switch,
and a switch doesn’t reset the session’s
attempt budget.
Payment authentication is unchanged
The per-card limit and the card switch apply only to the non-payment check. A payment authentication has nocardAttemptsRemaining and never returns
three-ds:card-attempts-exceeded. Once one has started on a session, a different card is
refused with 409 urn:radiumone:tokenization:session-not-bindable: to pay with another card,
start a new session. Re-authenticating the same card follows the rules in
Status meanings.
Handle the result
Any 2xx response is a result you must branch onstatus — never on response_code (that’s the verbatim host/acquirer code; useful for support tickets, not for your app logic).
After a timeout or a
5xx, replay with the same key. For every payment operation — purchase, authorize, capture, void, and both refunds — a replay of the identical request with the same request_id or operation_id is a lookup, not a resend, so it’s safe even after a 5xx that says retry_allowed: false (switch-timeout, database-unavailable). RadiumOne returns the outcome it recorded. If a capture, void, or referenced refund was sent but its outcome wasn’t recorded, RadiumOne asks the card network for the stored outcome instead of sending it again, and sends it only if the network never received it — so nothing is applied twice. A replay can return PENDING or REVERSAL_PENDING until the outcome settles. A request RadiumOne refused before it reached the card network (for example with device-settling or device-busy) is run again on the same transaction instead of returning a stored result — no second transaction is created. A capture that timed out after it may have reached the card network is reversed — the capture, never the authorization under it: while that reversal is open (REVERSAL_PENDING), a same-operation_id retry gets 409 tx:invalid-state-transition; once it clears, the hold is back to AUTHORIZED and the retry is sent as a new capture attempt. A capture that timed out before it left RadiumOne is sent as a new attempt on a same-operation_id retry — nothing was sent the first time. A void that timed out is reversed too: while that reversal is open, a retry gets 409 transaction:void-reversal-pending (retry_allowed: true); once it clears, the sale is back to CAPTURED and the retry is sent as a new attempt. While that earlier capture, void, or refund is unresolved, a follow-up with a different key on the same transaction gets 409 urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt: resend the pending request first. See Handle timeouts and unknown outcomes.PENDING means the outcome isn’t known yet — most often after a processor timeout. Don’t assume success or failure. Recover it one of two ways:
- Wait for a webhook (
payment.*,authorization.*,refund.*— see Webhook event types). - Poll
GET /v1/transactions/{id}/status— it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it readsPENDINGorREVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request;INCONSISTENTmeans stop and contact support; anything else is final. See Check a transaction’s status.
id yet — a client-side timeout before the first response arrived — replay the same purchase, authorize, or refund with the same request_id and body. The replay is a lookup, not a resend: it returns the stored transaction and its id, whatever status it’s reached, including PENDING or REVERSAL_PENDING. A capture or void replayed with the same operation_id works the same way, and for a capture, void, or referenced refund whose outcome wasn’t recorded, RadiumOne checks with the card network before sending anything. Never re-submit with a new idempotency key just because the first attempt is slow — that risks a second charge for the same order.
If the charge itself is rejected for a 3DS reason (for example
urn:radiumone:payment-gateway:three-ds:ref-invalid or
urn:radiumone:payment-gateway:three-ds:ref-expired), see
Authentication results
for remedies, or Handle 3D Secure failures in Elements
for the recovery-action version of the same failures.
Server policy
Token lifetime
The card token fromelements.submit() is transient (about 30 minutes) and the
3DS authentication is bound to it. Keep ttl_minutes at 30 or less for a 3DS
checkout. If the token lapses or the shopper switches cards mid-flow:
- Before charging:
authenticate()rejects withurn:radiumone:payment-gateway:three-ds:card-token-invalid(or one of theurn:radiumone:payment-gateway:token:*codes) — re-bind the card (elements.submit()again) and re-authenticate with the new token. - At charge time: the purchase/authorize call rejects with
422 urn:radiumone:payment-gateway:three-ds:card-token-mismatchif the charged token differs from the one that was authenticated — re-bind and re-authenticate rather than retrying the charge with the same ref.
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.Test your integration
See Test your integration for 3DS scenario coverage.Go-live notes
- Confirm your account has 3DS enabled before relying on this flow in production.
- Make sure your CSP allows the 3DS iframe/fetch origins — see Content Security Policy.
- Review the go-live checklist before launch.
Next steps
Challenge presentation and redirects
Customize where the challenge renders, and handle redirect return pages.
Authentication results
Every status, ECI value and 3DS error remedy.