How each works
Both modes end the same way: confirm the payment result from your server, with an authenticated
GET request or a webhook — never from the redirect query string or the postMessage payload alone. See Verify the payment result for the full decision table.
Redirect: full-page navigation
Your server creates a session, then your frontend sends the shopper’s whole browser tab tocheckout_url. The shopper briefly leaves your domain, pays on RadiumOne Checkout, and is redirected back to success_url or cancel_url — optionally signed, if you’ve configured a redirect secret.
Your server creates the session, the shopper’s whole browser tab goes to checkout_url and back, and your server confirms via webhook — not the redirect alone. See Redirect to hosted checkout for the full walkthrough, including how to handle the success and cancel returns.
Embedded: iframe on your page
Your server creates a session withmode: "embed", and your frontend mounts checkout_url in an <iframe> on the same page. The shopper never navigates away — they pay inside the iframe, which posts lifecycle and outcome events to your page via postMessage.
Your server creates the session with mode: "embed", your page renders checkout_url in an iframe, the iframe posts outcome events via postMessage, and your server confirms via webhook. See Embed hosted checkout for the full walkthrough, including the CSP and origin-checking requirements.
Which one to choose
- Default to redirect unless you have a specific reason to keep the shopper on your domain — it needs no domain registration and no CSP changes, and it behaves consistently across browsers and in-app WebViews.
- Choose embedded if keeping a consistent on-page experience matters more than the extra setup (domain registration, CSP
frame-src, and handling the FirefoxancestorOriginsfallback). - Either way, plan for the failure paths that are specific to each mode: Fix embedded checkout that won’t load and Debug missing embedded checkout events only apply to embedded mode; Handle abandoned checkouts and Handle expired checkout sessions apply to both.
Next steps
Redirect to hosted checkout
The simplest integration: create a session and redirect the shopper.
Embed hosted checkout
Keep the shopper on your domain with an iframe.
Embedded events reference
Every
postMessage event and payload shape.Verify the payment result
Confirm the outcome server-side before fulfilling.