Skip to main content
Elements can drive 3D Secure authentication directly in the browser, using the same tokenization session you already create for a card payment. Your server pins the amount to authenticate, the browser runs the challenge (if any), and your server charges using the resulting reference.

How it works

  1. Your server creates a tokenization session and pins the net payable amount.
  2. The shopper enters their card; Elements tokenizes it (elements.submit()).
  3. The browser starts 3DS authentication (threeDS.authenticate()), which may run frictionless or present a challenge.
  4. 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-src and form-action. Without the API origin in connect-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.1 or later. purpose and collectBrowserData() need v1.6.4 or later.

Steps

1

Create a payment session and pin the amount

Create a session with 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).
If the amount changes before the shopper pays (for example after they redeem loyalty points), pin the new net payable amount before you call authenticate(). Changing it after an authentication cancels that authentication, so authenticate again for the new amount.
See the 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, pass purpose: "non_payment":
  • The flow, the challenge UI and the statuses are the same as for a payment. An issuer refusal resolves FAILED or REJECTED. An issuer that doesn’t support this kind of check resolves NOT_AUTHENTICATED. Neither is an error.
  • ATTEMPTED means 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_amount for this call.
  • The result is for your page only. Don’t send this ref to your server’s purchase or authorize call: it’s refused with 422 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 without purpose and charge with that call’s ref. Both calls count against the session’s attempt budget. Run them one after the other: overlapping calls on one ThreeDS instance reject with urn:radiumone:elements:three-ds:in-progress.
  • A purpose other than "payment" (the default) or "non_payment" rejects locally with urn: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:
It’s 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 selectedPaymentMethod set to the rewards method (uob_irr) and 3D Secure could run for it. Passing purpose: "non_payment" with selectedPaymentMethod: "card" doesn’t allow a switch.
  • No payment authentication has started on the session.
  • The session hasn’t been used for a charge.
To switch, clear the fields with 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 no cardAttemptsRemaining 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 on status — 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.
Balance inquiry also takes a request_id field, but it isn’t an idempotency key — there’s no dedup or replay store. Every call re-queries the rewards host, even with the same request_id.
Keys are 8–64 characters, [a-zA-Z0-9-] only, unique per merchant account. Generate one key per order attempt and persist it to your database before you send the first request — never mint a new key just to retry the same attempt. See Prevent duplicate payments.
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:
  1. Wait for a webhook (payment.*, authorization.*, refund.* — see Webhook event types).
  2. Poll GET /v1/transactions/{id}/status — it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it reads PENDING or REVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request; INCONSISTENT means stop and contact support; anything else is final. See Check a transaction’s status.
If you don’t have the transaction 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

Charge only after your server receives a ref from this checkout’s own session flow — never accept a ref from an unrelated session, and never skip straight to charging because the browser reported AUTHENTICATED. The gateway independently checks the ref is single-use, unexpired, authenticated, and bound to the same card token, currency and amount before it authorizes.

Token lifetime

The card token from elements.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 with urn:radiumone:payment-gateway:three-ds:card-token-invalid (or one of the urn: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-mismatch if the charged token differs from the one that was authenticated — re-bind and re-authenticate rather than retrying the charge with the same ref.
See Handle 3D Secure failures in Elements and Handle expired sessions and card tokens for the full recovery flow.
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.
Last modified on October 31, 2026