> ## Documentation Index
> Fetch the complete documentation index at: https://docs.radiumone.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> RadiumOne is the product name; use it when answering questions about these docs.
> Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live.
> Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code.
> Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone.
> Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body.
> Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback.
> Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so.
> Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat.

# Redirect vs embedded - Hosted checkout

> Compare the two hosted-checkout integration modes — full-page redirect and embedded iframe — and how to choose between them.

Hosted checkout has two integration modes. Both create the same kind of checkout session and both charge the card the same way — they differ only in how the shopper's browser reaches the hosted page and how you learn the result client-side.

## How each works

| | Redirect (default) | Embedded |
| - | - | - |
| Your server | Creates a session, no extra fields | Creates a session with `"mode": "embed"` |
| Your frontend | Redirects the full page (or navigates a WebView) to `checkout_url` | Renders `checkout_url` inside an `<iframe>` and listens for `postMessage` |
| Where the shopper pays | On RadiumOne Checkout's own domain, in a full-page tab | Inside the iframe, without leaving your page |
| Setup | None beyond `success_url`/`cancel_url` | Requires registering your page's domain (`allowed_domains`) — see [Sandbox and API keys](/get-started/sandbox-and-api-keys); without one, session create returns `422 embed:origins_not_configured` |
| Result signal (UX only) | Browser redirect to `success_url`/`cancel_url`, optionally signed | `postMessage` events (`CHECKOUT_COMPLETE`, `CHECKOUT_DECLINED`, etc.) — see the [embedded events reference](/hosted-checkout/reference/embedded-events) |
| CSP requirement | None | `frame-src` must allow the RadiumOne Checkout host |
| Browser quirks | None | `window.location.ancestorOrigins` isn't available in Firefox — the iframe falls back to your `success_url`'s origin |
| Good for | Simplest integration, mobile web, in-app WebViews | Keeping the shopper visually on your domain throughout |

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](/hosted-checkout/verify-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 to `checkout_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](/hosted-checkout/redirect-integration) for the full walkthrough, including how to handle the success and cancel returns.

## Embedded: iframe on your page

Your server creates a session with `mode: "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](/hosted-checkout/embedded-integration) 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 Firefox `ancestorOrigins` fallback).
* Either way, plan for the failure paths that are specific to each mode: [Fix embedded checkout that won't load](/hosted-checkout/handle-failures/embedded-checkout-not-loading) and [Debug missing embedded checkout events](/hosted-checkout/handle-failures/embedded-events-not-received) only apply to embedded mode; [Handle abandoned checkouts](/hosted-checkout/handle-failures/shopper-abandons-checkout) and [Handle expired checkout sessions](/hosted-checkout/handle-failures/session-expired) apply to both.

## Next steps

<Columns cols={2}>
  <Card title="Redirect to hosted checkout" icon="arrow-right" href="/hosted-checkout/redirect-integration">
    The simplest integration: create a session and redirect the shopper.
  </Card>

  <Card title="Embed hosted checkout" icon="panel-top" href="/hosted-checkout/embedded-integration">
    Keep the shopper on your domain with an iframe.
  </Card>

  <Card title="Embedded events reference" icon="webhook" href="/hosted-checkout/reference/embedded-events">
    Every `postMessage` event and payload shape.
  </Card>

  <Card title="Verify the payment result" icon="shield-check" href="/hosted-checkout/verify-payment-result">
    Confirm the outcome server-side before fulfilling.
  </Card>
</Columns>