Embedded events - Hosted checkout

When a checkout session runs in mode: "embed", RadiumOne Checkout posts messages to the parent page via window.postMessage. Every message shares one envelope:

interface CheckoutMessage {
  source: "radiumone-checkout";
  type: "CHECKOUT_READY" | "CHECKOUT_COMPLETE" | "CHECKOUT_PENDING"
      | "CHECKOUT_DECLINED" | "CHECKOUT_EXPIRED" | "CHECKOUT_ERROR"
      | "CHECKOUT_RESIZE";
  data: Record<string, unknown>; // shape depends on `type` — see below
}

These events are not authenticated — any page can attempt to post a same-shaped message. Always check event.origin against the RadiumOne Checkout host and event.data.source === "radiumone-checkout" before handling a message, and never fulfil an order from an event alone. Confirm server-side — see Verify the payment result.

Origin rules

Listen for message events and filter on event.origin equal to the RadiumOne Checkout host your session’s checkout_url was served from.
RadiumOne only posts to your page’s origin if that origin is in your registered allowed_domains. On browsers that expose window.location.ancestorOrigins (Chrome, Safari), the real parent-frame origin is used; Firefox doesn’t expose it, so RadiumOne falls back to the origin derived from your success_url — make sure that origin matches your embedding page.

Events

event

The card form has finished loading in the iframe.

Show data

string

The session’s checkout_id.

event

The iframe’s content height changed — resize your <iframe> element to match.

Show data

number

New content height in pixels.

event

The payment was approved. Advisory only — confirm with your server before fulfilling.

Show data

string

The session’s checkout_id.

string

Always "completed".

string | null

The gateway transaction ID, if available.

string | null

Last four digits of the card used.

string | null

Card brand, if known.

event

The payment outcome isn’t known yet (asynchronous processing). Wait for a webhook or poll your server.

Show data

string

The session’s checkout_id.

string

Always "processing".

string | null

The gateway transaction ID, if available.

event

The payment was declined.

Show data

string

The session’s checkout_id.

string

Verbatim issuer/acquirer response code — for diagnostics, not branching logic.

event

The session’s TTL elapsed while the shopper was submitting payment.

Show data

string

The session’s checkout_id.

event

A network or client-side error interrupted the payment attempt — see Handle payment service outages during checkout.

Show data

string

The session’s checkout_id.

string

Error code (for example "NETWORK").

string

Human-readable error message.

There is no CHECKOUT_CANCELLED event today — a shopper closing or navigating away from the iframe does not post a message. See Handle abandoned checkouts for how to detect this case instead.

Example listener

window.addEventListener("message", (event) => {
  if (event.origin !== CHECKOUT_ORIGIN) return;
  const msg = event.data;
  if (!msg || msg.source !== "radiumone-checkout") return;
  // handle msg.type / msg.data
});

See Embed hosted checkout for the full integration guide, or Embedded checkout errors if your listener never fires or the iframe won’t load.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Embedded events - Hosted checkout

Origin rules

Events

Example listener

​Origin rules

​Events

​Example listener

Origin rules

Events

Example listener