How it works
- The shopper enters their card on your own payment form, so the card details are in your PCI DSS scope.
- Your 3DS provider authenticates the shopper with those card details.
- Your server charges with the card details plus the result your provider returned.
Before you begin
This path is available on request and is off by default. Request enablement for both of these:- Your own 3DS results, per outlet. Without it, the charge is rejected with
422 urn:radiumone:payment-gateway:three-ds:external-auth-not-permitted. - Card details on the terminals that take the payment. Without it, the
charge is refused with
409 urn:radiumone:payment-gateway:routing:raw-card-not-permittedbefore anything is sent. See Send card details instead of a token.
Steps
1
Collect the card details
Collect the card number, expiry date and (optionally) security code on your
own payment form. These systems are in your PCI DSS scope.
2
Authenticate with your own 3DS provider
Run your own 3DS integration (AReq/ARes/CReq) however you already do
today. This happens entirely outside RadiumOne. Collect the ECI, the
directory server transaction ID, the 3DS protocol version, the CAVV (or AAV)
if one was produced, and the transaction status (
Y or A).3
Charge with the card details and the provider's evidence
From your server, purchase or authorize with the card details in
A RadiumOne card token in
card.pan, card.expiry and card.cvv, and three_ds.mode set to
"external_auth" with the evidence fields alongside it. Without mode: "external_auth", the evidence
fields are rejected. API reference: purchase · API reference: authorize.card.token is also accepted with
"external_auth", but RadiumOne can’t give your provider the card number
behind it.If the charge is rejected, see Handle 3DS failures with your own provider.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.
Errors specific to this path
The two errors you’re most likely to hit on this path areurn:radiumone:payment-gateway:three-ds:external-auth-not-permitted (your outlet isn’t enabled — see
Before you begin) and urn:radiumone:payment-gateway:validation-error (a
three_ds field breaks a field rule, an unrecognized key was sent, or the
result is inconsistent for the card’s scheme). Where 3DS is required, a result that
doesn’t show authentication fails with
urn:radiumone:payment-gateway:three-ds:authentication-required — see
When your result satisfies a 3DS requirement. For the full 3DS error reference with HTTP
codes and remedies, see
Authentication results.
ECI values
The electronic commerce indicator (ECI) your provider returns determines whether liability shifts to the issuer:Field rules
Send these in thethree_ds object, next to "mode": "external_auth". A field
that breaks a rule returns 400 urn:radiumone:payment-gateway:validation-error
with a pointer to the field; the message never repeats the value you sent.
Unknown keys in the
three_ds object are rejected. Once the card’s scheme is
known, a Visa-family or Mastercard result whose authentication_status
contradicts its ECI (for example Y with Visa ECI 06), or whose cavv is too
long for the scheme, also returns 400 urn:radiumone:payment-gateway:validation-error
(pointer /three_ds/authentication_status or /three_ds/cavv), rather than being
sent on to be declined.
When your result satisfies a 3DS requirement
Where 3DS is required, your result counts only if all of these hold:- The ECI shows authentication for the card’s scheme:
05or06for Visa, JCB, American Express and Diners;02or01for Mastercard and Maestro. - A
cavvis present. - Any
authentication_statusyou send agrees with the ECI.
422 urn:radiumone:payment-gateway:three-ds:authentication-required. A result for a
Discover or UnionPay card, or a card whose scheme can’t be identified, never
satisfies a requirement: use RadiumOne 3DS
for those cards. For them, RadiumOne doesn’t check your authentication_status
or cavv against the scheme and doesn’t forward your authentication_status.
Where 3DS isn’t required, such a result is still accepted. A result without a
cavv (an attempt with no cryptogram) is forwarded but never satisfies a
requirement.
Limitations
- No 3DS1. Only 3DS2 evidence is accepted — there’s no
xidfield, so a provider that only supports 3DS1 can’t use this path. - Merchant-asserted evidence. RadiumOne doesn’t independently verify the CAVV or ECI you submit — it trusts your provider’s result, and liability for that result rests with you and your provider. Make sure your own integration validates the ARes/RReq signature before you submit its fields here.
- UOB Rewards sales. On a purchase that redeems rewards, your
authentication_statusis ignored: the status is derived from the ECI alone, and a cavv or status isn’t checked against the scheme. See Rewards with 3D Secure.
Server policy
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 scenario coverage.Go-live notes
- Confirm both enablements (your own 3DS results for the outlet, and card details on its terminals) before relying on this path in production.
- Keep your provider’s evidence validation server-side; never trust values that could originate from the browser.
- Review the go-live checklist before launch.
Next steps
3D Secure overview
Compare this path against RadiumOne’s built-in 3DS.
Security and PCI scope
PCI scope per integration path.