What the shopper sees
- Card payments: after the shopper enters their card and pays, the issuer may approve straight away, or ask the shopper to confirm (a one-time passcode or a banking app approval). The challenge appears in a frame inside the payment page, never as a full-page redirect.
- Rewards payments: before the shopper’s rewards balance is shown, the issuer may ask them to confirm they’re the cardholder. When they pay, the card part of the payment is authenticated again for the amount left after the redemption. A payment fully covered by vouchers charges nothing to the card and needs no authentication.
- If the check before the rewards balance fails: the shopper can try the same card again, and the payment page tells them when one try is left (“You can try this card one more time.”). Each card gets 3 issuer challenges per checkout session, and a successful check restores them. After that, the page clears the card and asks for a different one (“Try a different card”; “We couldn’t verify this card with your bank after 3 attempts, so it can’t be used for this checkout. You haven’t been charged. Please enter a different card.”). The shopper can use up to 3 cards in a session, counting the first and counting a return to an earlier card. After that they see “You’ve tried the maximum number of cards for this checkout. Please return to the store and start again.”, with a Return to the store link, and nothing is charged. The session also has an overall limit on authentications across all cards, which can end the check sooner: nothing is charged, and the shopper starts a new checkout.
- What you see after the card limit: Return to the store only redirects the shopper to your
cancel_url, withoutstate. It doesn’t cancel the session and no webhook is sent, so the session stayspendinguntilexpires_at, then becomesexpired. While it’spending, creating a session with the sameorder_reference, amount and currency returns that same session, which puts the shopper back on the same checkout. To let them start again, cancel the session first, or create the new one with a neworder_reference. - Retries and card switching apply only to that check. Authentication of the card amount when the shopper pays is unchanged: there’s no retry and no card switch, so a failure ends as described below.
- If authentication fails (the issuer declines it, or the shopper cancels or runs out of time), the payment isn’t charged. The shopper sees a failure screen that says what happened (for example, “Verification timed out”), with a reference (the last 8 characters of your
checkout_id) and a Return to the store link, and can’t retry from it. You handle the outcome the same way as any other declined payment. - If the session ends during a challenge (the shopper takes longer than the session’s lifetime), the payment isn’t charged. The shopper sees “Your session has ended”, with a link back to your store to start a new checkout, and the session is
expired. Handle it as in Session expired. - If the issuer can’t authenticate the card, the payment continues without 3D Secure. Where 3D Secure is required for it, the payment fails instead.
postMessage event or webhook for 3D Secure, including these rewards limits: you don’t call an API or handle an error for them. You handle the outcome exactly as you do today: see Handle failures for the failure scenarios that apply to every hosted-checkout payment.
Send billing details
Send the shopper’sbilling_details when you create the checkout session. Hosted checkout passes them to the card issuer for 3D Secure, and issuers approve more payments without a challenge when they get them. At minimum, send the cardholder’s name and an email or phone number. The address is optional.
Values longer than 3D Secure accepts (name 120 characters, address lines 60, city 50, postal code 10) aren’t sent to the issuer, and state is sent only for a US or Canadian address with a 2-letter code. They’re still shown on the payment page. See Customize checkout: shopper and billing details for the full field table and an example request.
Allowed origins
After a challenge, RadiumOne shows a short completion page inside the challenge frame. A browser shows it only if every page around that frame is served overhttps:// and is allowed for your account. That allowed origins list is separate from the allowed_domains used for your redirect URLs.
- Redirect mode: nothing to register. The hosted checkout origin is allowed for every merchant automatically.
- Embedded mode: the challenge frame sits inside the payment page, which sits inside your page. The hosted checkout origin is still allowed automatically, but your page that embeds the checkout must be on your allowed origins. Contact support to add each
https://origin that embeds the checkout, in sandbox and production. Without it, the shopper can see a blocked frame and the outcome arrives later. Your page’sframe-srcstill only needs the hosted checkout origin.
Before you go live
- Whether 3D Secure runs, and whether it’s required, is set on your RadiumOne account per outlet. Contact support to enable it.
- RadiumOne hasn’t published 3D Secure test cards yet. See Test your integration.
Next steps
Customize checkout
The full
billing_details field reference.3D Secure
How 3D Secure works across every integration path.