Skip to main content
3D Secure (3DS) adds an issuer authentication step to a card payment. A successful authentication can shift liability for fraud-related chargebacks from you to the card issuer. RadiumOne supports 3DS across the integration grid, with the depth of support varying by row and column.

Frictionless vs. challenge

Every 3DS attempt resolves in one of two ways:
  • Frictionless: the issuer authenticates the shopper using risk signals alone (device data, transaction history). No shopper interaction. This is the fastest path and the outcome you should design for by default.
  • Challenge: the issuer isn’t confident enough and asks the shopper to prove their identity — a one-time passcode, a banking app approval, or biometrics — inside a visible frame or a redirect. See Challenge presentation and redirects.
A third outcome, decoupled authentication, lets the shopper approve out-of-band (for example in their banking app) while your checkout page polls for the result.

3D Secure across the integration grid

  • Hosted checkout (redirect or embedded) — 3D Secure available.
  • Elements + Payments API — 3D Secure available.
  • Payments API + your own 3DS provider — you collect the card details (your PCI scope) and send them with your provider’s result, available on request and enabled per outlet.
Compare these against the full 2x3 grid on Choose your integration.

Amount rules

3DS authenticates a specific amount, and the gateway enforces that the amount you authenticate is the amount you later charge:
  • Every checkout session has a gross amount (session amount, plain integer minor units) and a net_payable_amount: the amount the card is charged, which is what 3DS authenticates. For a plain card sale, send net_payable_amount equal to amount when you create the session.
  • If you redeem loyalty points or another deduction against the same session, pin the actual card-charged amount with PATCH /v1/sessions/{session_id} (net_payable_amount) before the browser calls authenticate(). 3DS then authenticates the net amount, not the gross. A session with no net_payable_amount can’t start a payment authentication: authenticate() rejects with urn:radiumone:payment-gateway:three-ds:session-not-amount-bound.
  • Sending the same net_payable_amount again always succeeds and leaves any authentication untouched. Sending a different value cancels the session’s current payment authentication: its ref reads EXPIRED, and a charge that presents it fails with 422 urn:radiumone:payment-gateway:three-ds:ref-invalid. Run authenticate() again for the new amount. While a charge that presents one of the session’s refs is still in progress, a different value is refused with 422 urn:radiumone:payment-gateway:sessions:amount-not-pinnable; wait for that charge’s outcome first.
  • At purchase time, the gateway checks the three_ds.ref was authenticated for a session whose (possibly net-payable) amount matches the charge. A mismatch returns 422 urn:radiumone:payment-gateway:three-ds:amount-exceeds-authenticated. Charging a different card token than the one that was authenticated returns urn:radiumone:payment-gateway:three-ds:card-token-mismatch.
Amounts are always integers in the currency’s minor units. For example, 5000 for SGD means SGD 50.00. Only currencies with 2 minor units are accepted today — read each currency’s minor units from the API rather than from your own table. See Currencies and amounts.

The 3DS reference

A successful authenticate() gives you a ref to send on the purchase or authorize call as three_ds: { ref }.
  • It expires. A ref is valid for about 15 minutes from the start of the authentication. Completing the challenge doesn’t extend it. Charge within that window, or the charge fails with 422 urn:radiumone:payment-gateway:three-ds:ref-expired.
  • It’s single-use. The gateway uses it up only when it sends the charge to the acquirer. If the charge is refused before that (for example a 400 validation error), the ref stays usable, so a retry with the same request_id can still carry it.
  • A NOT_AUTHENTICATED result also has a ref. You can send it: the charge then goes through without authentication, still bound to the same card and currency. Where 3DS is required, it’s refused with 422 urn:radiumone:payment-gateway:three-ds:authentication-required.
  • A failed authentication doesn’t end the checkout. After FAILED, REJECTED, NOT_AUTHENTICATED or EXPIRED, the session stays open, and you can call authenticate() again on it without re-entering the card. Every attempt counts against the session’s attempt budget.

Cardholder billing data

Issuers approve more authentications without a challenge when they receive the cardholder’s details. Send them from your server as billing when you create the session (POST /v1/sessions) or later with PATCH /v1/sessions/{session_id} (a PATCH replaces any billing sent earlier):
  • Send the cardholder name plus an email or a phone_number (both is better). The address fields (address1 to address3, locality, postal_code, country) are optional.
  • Send administrative_area only for US and Canadian addresses.
  • Omit any field you don’t hold. Never send an empty string.
  • A field that fails validation returns 400 urn:radiumone:payment-gateway:validation-error naming the field.
RadiumOne keeps billing data encrypted, uses it only for this session’s 3DS authentication, and erases it once an authentication succeeds or a charge uses it. After a failed authentication it’s kept, so a retry on the same session still has it.

When 3DS is required

Whether 3DS runs, and whether it’s required, is set on your RadiumOne account for each acquirer and channel. You don’t choose it per request.
  • A requirement applies only where 3DS can run for your account. If 3DS isn’t available for that acquirer and channel, the charge goes through without authentication, and authenticate() resolves NOT_AUTHENTICATED. You can still send your own provider’s result if your outlet is enabled for it.
  • The session response’s three_ds_requirement is a hint to prepare your checkout, for a card payment on the session’s channel. mandatory: true (status: "expected") means card payments are expected to need 3DS, and a payment without it is refused. possible means 3DS can run and may be requested, off means RadiumOne won’t run 3DS, and not_applicable means the channel can’t run 3DS. The final decision is made at the 3DS step once the card is entered, for example where a rule applies to particular cards or the payment includes a rewards redemption.
  • If you take payments through payment links, send "channel": "PAYMENT_LINK" when you create the session, so the payment-link 3DS rules apply. Omitted means ECOMMERCE. You can’t change it later.
  • A charge that needs 3DS and doesn’t carry a satisfying three_ds fails with 422 urn:radiumone:payment-gateway:three-ds:authentication-required.
  • 3DS is never required on a standalone refund.
  • A rewards payment fully paid by vouchers whose values add up exactly to the sale amount charges nothing to the card, so it needs no 3DS. A full redemption with points still needs it, because the points value isn’t final until the rewards program answers.
  • A session whose net_payable_amount is 0 needs no authentication: authenticate() resolves NOT_AUTHENTICATED straight away.

Verify the cardholder without a payment

You can also authenticate the cardholder when no payment is being made, for example before showing a rewards balance. With Elements, pass purpose: "non_payment" to authenticate(); see Verify the cardholder without a payment. The result is for your checkout page only: it authenticates no amount, and a charge that presents its ref fails with 422 urn:radiumone:payment-gateway:three-ds:ref-purpose-mismatch. Run a separate payment authentication before you charge. A non-payment authentication allows 3 challenges per card per checkout session: see Limits on the cardholder check.

Server policy

Charge a 3DS-required order only with a valid three_ds.ref obtained from that checkout’s own session flow — unless you deliberately accept the risk of a non-3DS payment (by omitting three_ds, or sending {mode:"unauthenticated"}). Never branch on the client-reported 3DS status to decide whether to charge, or to decide liability. The client status only drives your UX (for example, showing a decline instead of submitting the payment) — the gateway independently validates the ref at purchase time (single-use, unexpired, authenticated, and matching token/currency/amount) and rejects the charge otherwise.

Non-3DS payments

You can omit three_ds entirely, or send {mode:"unauthenticated"} to record that you deliberately skipped authentication; the two mean the same. three_ds carries exactly one of ref, mode: "unauthenticated", or mode: "external_auth" with your own provider’s result. If you omit it where 3DS is required (see When 3DS is required), the purchase or authorize call fails with 422 urn:radiumone:payment-gateway:three-ds:authentication-required. Only the ECOMMERCE and PAYMENT_LINK channels can require 3DS: a RECURRING (merchant-initiated) charge, or one on any other channel, is never refused for missing authentication.
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

Authenticate in the browser and charge with the resulting ref.

Use your own 3DS provider

Bring externally-produced 3DS evidence to a charge.

Challenge presentation and redirects

Iframe, modal, decoupled and redirect challenge flows.

Authentication results

Status meanings, ECI values and 3DS error remedies.
Last modified on October 31, 2026