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.
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 bythreeDS.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: aserr.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
Everyauthenticate() 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.