Skip to main content
This page is the single reference for 3D Secure statuses, ECI values and error codes across 3DS with Elements, Challenge presentation and Your own 3DS provider. For the recovery-action version of the same errors, see Handle 3D Secure failures in Elements.

Status meanings

threeDS.authenticate() and threeDS.resume() resolve with { status, ref }. A decline resolves — it never throws. Use the status only to drive your UX; your server action is the same regardless (see Server policy). After any of the last four, the session stays open: you can call authenticate() again without re-entering the card, within the attempt budget. The exception is a non-payment check on a card with no attempts left. PENDING and DECOUPLED are intermediate states the SDK handles internally (polling on your behalf) and are never returned as a final result — see Decoupled authentication. Any other status value fails closed: the SDK rejects with urn:radiumone:elements:three-ds:action-malformed rather than resolving it. The SDK waits at most 5 minutes, even if the issuer allows longer. A challenge still open after 5 minutes rejects with urn:radiumone:elements:three-ds:challenge-timeout; a decoupled approval still pending resolves EXPIRED. For a non-payment check (purpose: "non_payment"), the statuses mean the same, but the ref is never sent to your server’s charge.
Whatever the status, your server must still independently verify the ref at charge time. Never skip that check because the client reported AUTHENTICATED — see Server policy.

ECI meanings

The electronic commerce indicator (ECI) records how strongly a card scheme backs an authentication, and whether liability shifts to the issuer. RadiumOne’s own 3DS flow doesn’t currently return the ECI to your server. If you use your own 3DS provider, you submit the ECI yourself; see the full ECI table there.

Error codes

Every 3D Secure error code is a URN. Match the whole code, never a prefix or the text after the last : (not-found, for example, appears in several namespaces). Branch on err.retryAllowed, never on the HTTP status: the two 429s below need opposite handling. Treat a code you don’t recognize as not retryable unless retryAllowed is true, and never authorize after an error.

SDK errors

These are thrown by threeDS.authenticate()/handle()/resume() in the browser, before your server is ever involved. The 3D Secure errors table lists every code with its retryAllowed value.

Gateway errors

Gateway codes reach you two ways: as err.code when authenticate() rejects, and in the problem response to your server’s purchase or authorize call.

While authenticating

authenticate()’s first call to the API can reject with a Payments API error code, passed through verbatim as err.code. The 3D Secure errors table defines each one with its HTTP status. This is what to do:
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.
That first call also picks the acquirer and checks your outlet, so routing and outlet refusals (urn:radiumone:payment-gateway:routing:*, urn:radiumone:payment-gateway:checkout:*, urn:radiumone:payment-gateway:merchant:outlet-disabled) can arrive here too — see the full table. Any other urn:radiumone:payment-gateway:* code is from the API, not the SDK: log it, show a generic failure, and never authorize.

Attempt budget

Every authenticate() call counts against the session’s 3DS attempt budget, including one that fails a later check. Don’t call authenticate() again in a loop after a 4xx error: fix the cause first (re-bind, fix the argument, or create a new session). Once the budget is spent, authenticate() rejects with urn:radiumone:payment-gateway:three-ds:session-attempts-exceeded and only a new session helps. That’s why the two 429s differ:

At charge time

These come from your server’s purchase or authorize call, after 3D Secure finished in the browser: The charged card token must be the one that was authenticated. If it isn’t, the charge fails with urn:radiumone:payment-gateway:three-ds:card-token-mismatch, even though 3D Secure returned AUTHENTICATED. Re-bind and run 3D Secure again; don’t retry the charge with the same token and 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.

Next steps

3DS with Elements

Where these statuses and errors come from in the authenticate/charge flow.

Use your own 3DS provider

ECI values you submit yourself on this path.
Last modified on October 31, 2026