Skip to main content
If you already run 3D Secure through your own MPI (merchant plug-in) or a third-party authentication provider, you can bring the result to a RadiumOne charge instead of using RadiumOne’s built-in 3DS. You collect the card details yourself, in your own PCI DSS scope, authenticate with your provider, and send RadiumOne the card plus the 3DS result. RadiumOne never gives your provider the card number, so Elements isn’t used on this path. When you use your own 3DS provider, you collect the card details yourself and send them to RadiumOne with your provider’s result, so your payment form, your server and your 3DS provider are in your PCI DSS scope. RadiumOne never passes the card number to your provider. Confirm your PCI DSS scope with your assessor before you go live.

How it works

  1. The shopper enters their card on your own payment form, so the card details are in your PCI DSS scope.
  2. Your 3DS provider authenticates the shopper with those card details.
  3. 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:

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 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.
A RadiumOne card token in 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 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.

Errors specific to this path

The two errors you’re most likely to hit on this path are urn: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 the three_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: 05 or 06 for Visa, JCB, American Express and Diners; 02 or 01 for Mastercard and Maestro.
  • A cavv is present.
  • Any authentication_status you send agrees with the ECI.
Otherwise the charge fails with 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 xid field, 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_status is 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

Charge only after your own 3DS provider has returned a verified result for this checkout attempt — never submit placeholder or reused evidence, and never charge based on a client-reported outcome your server hasn’t independently confirmed came from your provider.
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.
Last modified on October 30, 2026