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.
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(sessionamount, plain integer minor units) and anet_payable_amount: the amount the card is charged, which is what 3DS authenticates. For a plain card sale, sendnet_payable_amountequal toamountwhen 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 callsauthenticate(). 3DS then authenticates the net amount, not the gross. A session with nonet_payable_amountcan’t start a payment authentication:authenticate()rejects withurn:radiumone:payment-gateway:three-ds:session-not-amount-bound. - Sending the same
net_payable_amountagain always succeeds and leaves any authentication untouched. Sending a different value cancels the session’s current payment authentication: itsrefreadsEXPIRED, and a charge that presents it fails with422 urn:radiumone:payment-gateway:three-ds:ref-invalid. Runauthenticate()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 with422 urn:radiumone:payment-gateway:sessions:amount-not-pinnable; wait for that charge’s outcome first. - At purchase time, the gateway checks the
three_ds.refwas authenticated for a session whose (possibly net-payable) amount matches the charge. A mismatch returns422 urn:radiumone:payment-gateway:three-ds:amount-exceeds-authenticated. Charging a different card token than the one that was authenticated returnsurn: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 successfulauthenticate() gives you a ref to send on the purchase or authorize
call as three_ds: { ref }.
- It expires. A
refis 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 with422 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
400validation error), therefstays usable, so a retry with the samerequest_idcan still carry it. - A
NOT_AUTHENTICATEDresult also has aref. 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 with422 urn:radiumone:payment-gateway:three-ds:authentication-required. - A failed authentication doesn’t end the checkout. After
FAILED,REJECTED,NOT_AUTHENTICATEDorEXPIRED, the session stays open, and you can callauthenticate()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 asbilling 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
nameplus anemailor aphone_number(both is better). The address fields (address1toaddress3,locality,postal_code,country) are optional. - Send
administrative_areaonly 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-errornaming the field.
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()resolvesNOT_AUTHENTICATED. You can still send your own provider’s result if your outlet is enabled for it. - The session response’s
three_ds_requirementis 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.possiblemeans 3DS can run and may be requested,offmeans RadiumOne won’t run 3DS, andnot_applicablemeans 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 meansECOMMERCE. You can’t change it later. - A charge that needs 3DS and doesn’t carry a satisfying
three_dsfails with422 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_amountis0needs no authentication:authenticate()resolvesNOT_AUTHENTICATEDstraight 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, passpurpose: "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
Non-3DS payments
You can omitthree_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.