How it works
- The shopper clicks Pay on your site.
- Your server calls
POST /api/v1/checkout/sessionswith your secret key. - RadiumOne Checkout returns
checkout_url. - Your server redirects the shopper’s browser to
checkout_url. - The shopper enters their card on the hosted page.
- RadiumOne Checkout charges the card via the Payments API.
- RadiumOne sends your webhook endpoint a
payment.captured(or decline/failure) event — confirm the result from here, not from the redirect alone.
Before you begin
You need a secret key (
r1sk_…) and a success_url/cancel_url pair on a domain you control. See Sandbox and API keys and Checkout API authentication for how the X-Api-Key header works.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.Return URL requirements
success_url and cancel_url must be absolute https:// URLs, up to 2048 characters each — http://localhost is also accepted, for local development. Anything else, including a URL that doesn’t parse at all, is rejected at create with 400 validation:invalid_input. The host is also checked against your account’s allowed_domains — an exact match, or a subdomain of a configured domain; any host is accepted if you haven’t configured an allow-list, and a host outside the list returns 403 security:domain_not_allowed.
Steps
1
Create a checkout session
Call the create-session endpoint from your server with the order amount, currency, your own Sending the same
order_reference, and the pages to return to.order_reference again within the session’s TTL returns the existing session instead of creating a duplicate — safe to retry on a network error.See Prevent duplicate sessions and double payments for the race case and for retrying after a decline.2
Redirect the shopper
Redirect the shopper’s browser (HTTP redirect or a client-side navigation) to
data.checkout_url from the response. Don’t fetch or embed this URL — it’s a full page for the shopper to visit directly.3
Handle the success return
When the payment completes, RadiumOne redirects the shopper to your
success_url with checkout_id (and state, if you sent one). If you’ve configured a redirect secret, the URL also carries status, transaction_id, ts, and sig — see Verify the payment result before treating this as anything more than a UX signal.4
Handle the cancel return
Three different outcomes all return the shopper to your raw
cancel_url — none of them carry checkout_id or state, so you can’t tell them apart from the query string alone:Put your own order reference in the
cancel_url itself (for example cancel_url=https://shop.example.com/pay/cancel?order=ORD-1024) so you can correlate the return without relying on query params RadiumOne doesn’t send on this path.Always re-check the session status from your server before deciding an order failed — see the next step.Handle the result
Never fulfil an order from the redirect URL alone. Confirm the outcome with an authenticatedGET request or a webhook — see Verify the payment result for the full decision table.
Test your integration
See Test your integration for sandbox scenarios covering approvals, declines, timeouts, and cancellations.Go-live notes
- Register your production
success_url/cancel_urldomains if you’ve setallowed_domains. - Configure a redirect secret so success returns are signed — see Verify the payment result.
- Set up your webhook endpoint before going live; it’s the authoritative source of truth, not the redirect.
Next steps
Verify the payment result
Confirm the outcome server-side before fulfilling.
Session lifecycle
Statuses, TTL, cancellation, and retries.
Handle failures
Ten common failure scenarios and what to do for each.