threeDS.authenticate() and threeDS.resume() fail in one of two shapes: a rejected promise (a flow-level error — CSP, cancellation, a stale token, a gateway refusal) or a resolved decline ({status} other than AUTHENTICATED/ATTEMPTED, which isn’t an error at all). Telling these apart decides whether you retry the authentication or restart the checkout.
TL;DR:
authenticate()/resume() rejects or resolves to a non-authenticated status → tell a flow error (retry the authentication) apart from an issuer decline (don’t auto-retry).When this happens
- The shopper cancels a challenge in progress, or the challenge window expires before they complete it.
- Your Content Security Policy blocks the SDK’s
connect-src,frame-srcorform-actionneeds, so the challenge can’t load or a completed challenge can’t be confirmed. - Your checkout page isn’t
https://or isn’t on your account’s allowed-origins list, so the completion page after a challenge shows as a blocked frame. authenticate()runs beforeelements.submit()resolved, or with a session, secret or publishable key that doesn’t match this checkout.- The card token from an earlier
elements.submit()lapsed (about 30 minutes), was revoked, or doesn’t match the session beforeauthenticate()runs. selectedPaymentMethodis missing, or names a method that isn’t offered for this checkout.- The session has used up its 3DS attempt budget.
- The 3DS provider itself is unreachable, or the gateway rejects the reference at charge time because it’s unknown, reused, expired, bound to a different amount/card, or from a non-payment check.
- On a redirect return page, the issuer’s result hasn’t landed within the 30 seconds
resume()waits.
What you see
… repeats the prefix of the first code in the same cell. Every code is defined, with its HTTP status and remedy, on Authentication results and 3D Secure errors.
What to do
1
Branch on rejection vs. resolution first
A
catch means the flow broke (fix the integration or let the shopper retry the authentication itself). A resolved non-authenticated status means the issuer declined — don’t automatically retry the same authentication; see Authentication results for the full status table and the server action for each.2
Match the whole code, and never loop on a 4xx
Compare
err.code with the full URN and branch on err.retryAllowed, never on the HTTP status. Every call authenticate() makes to start 3D Secure counts against the session’s attempt budget, even one that fails, so don’t call authenticate() again until you’ve fixed the cause. Once the budget is spent, only a new session helps — see Attempt budget.3
Restart checkout on an unauthorized session
urn:radiumone:payment-gateway:auth:three-ds-browser-unauthorized means the publishable key, sessionId or sessionSecret isn’t valid for this checkout. If it happens every time, pass the sessionId and sessionSecret from the same POST /gateway/v1/sessions response. Otherwise the session expired: restart checkout with a new session.4
Wait for submit() before authenticate()
urn:radiumone:payment-gateway:not-found from authenticate() means the card token is unknown, usually because authenticate() ran before elements.submit() resolved. Await submit() and pass this session’s BindResult.token.5
Pass a payment method the checkout offers
urn:radiumone:elements:three-ds:missing-payment-method is raised locally, before any network call, when selectedPaymentMethod is missing, empty or over 32 characters. urn:radiumone:payment-gateway:checkout:payment-method-not-offered means the value isn’t offered for this checkout: pass a payment_methods[].type from GET /gateway/v1/payment-methods, such as card.6
Check CSP before assuming a provider outage
urn:radiumone:elements:three-ds:challenge-timeout is most often a missing connect-src, frame-src or form-action directive, not an actual provider outage — see Content Security Policy: troubleshooting. A 404 from the status check isn’t a timeout: it rejects straight away with urn:radiumone:elements:three-ds:action-not-found. Restart the payment.7
Re-bind and re-authenticate on a stale token
urn:radiumone:payment-gateway:three-ds:card-token-invalid, urn:radiumone:payment-gateway:token:revoked, urn:radiumone:payment-gateway:token:transient-expired or urn:radiumone:payment-gateway:token:data-purged from authenticate(), or a charge-time urn:radiumone:payment-gateway:three-ds:card-token-mismatch, all mean the token no longer matches what you’re authenticating or charging — call elements.submit() again for a fresh token, then authenticate() again, rather than retrying the charge alone.8
Call resume() again after a timeout on the return page
urn:radiumone:elements:three-ds:challenge-timeout from resume() means no final result arrived within 30 seconds. The pending reference is kept and the authentication may already have succeeded, so call resume() again (or let the shopper reload) before you treat it as a failure.9
Finish the charge if the session lapsed during a challenge
A challenge or decoupled authentication can finish after your tokenization session expired. You can still charge it: send the purchase from your server with the same
card.token and three_ds.ref, the same currency, and an amount no higher than the authenticated amount, before the ref expires (about 15 minutes from the start of authentication) and while the card token is still valid. A different card token returns 422 urn:radiumone:payment-gateway:three-ds:card-token-mismatch: authenticate again for that token. If you don’t charge, nothing is charged and the shopper starts again.10
Never reuse a ref across charges
urn:radiumone:payment-gateway:three-ds:ref-invalid or urn:radiumone:payment-gateway:three-ds:ref-expired at charge time means the reference is single-use and already consumed, cancelled by a change to the session’s net payable amount, or too old — re-authenticate for a new ref rather than resending the same charge body with a new request_id. urn:radiumone:payment-gateway:three-ds:ref-purpose-mismatch means you sent the ref from a purpose: "non_payment" check: run a payment authentication and charge with its ref.Prevent it
- Keep
ttl_minutesat 30 or less for a 3DS checkout, matching the card token’s own lifetime — see Token lifetime. - Ship your CSP as
Content-Security-Policy-Report-Onlyfirst so a missingconnect-src,frame-srcorform-actiondirective surfaces in reports instead of manifesting as a shopper-facing challenge timeout in production.
Test it
See Test your integration for 3DS scenario coverage.Related
3DS with Elements
The authenticate-then-charge flow these failures interrupt.
Authentication results
Every status, SDK error, and gateway error, with the remedy for each.