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

# How Embedded Checkout Works

> Architecture and postMessage event flow of the Caibo embedded checkout SDK that renders the payment page inside your website without a full-page redirect.

# Overview

The Caibo embedded checkout is a drop-in JavaScript SDK that renders the Caibo payment page **inside** your website as an inline container or full-screen modal overlay — no full-page redirect required. The customer never leaves your site, and your servers never touch raw card data.

## Architecture

The SDK creates an `<iframe>` that hosts the Caibo payment UI. You choose between two display modes:

* **Inline mode** — the iframe is mounted into a `<div>` on your page (ideal for single-page checkout flows).
* **Modal mode** — the SDK injects a centered modal with backdrop overlay onto `<body>` (no container element required).

```text theme={null}
Merchant backend                       Merchant page (browser)
├── apiKey (long-lived secret)         ├── Receives { requestId, token } from your backend
│                                      │
├── POST /payment-requests             ├── Inline mode                          Modal mode
│   → returns requestId                │   ├── <div id="caibo-checkout">        ├── SDK overlay on <body>
│                                      │   │     └── <iframe ...?token=…&       │     └── <iframe ...?token=…&
├── POST /payment-requests/{id}/       │   │           requestId=…&             │           requestId=…&
│        checkout-session              │   │           embedded=true>           │           embedded=true>
│   → returns token (15-min TTL)       │   │             └── Payment UI         │             └── Payment UI
│                                      │
└── Sends { requestId, token }         └── postMessage events flow back to the parent window
    to the browser                            payment.ready    → checkout page has loaded
                                              payment.success  → payment completed successfully
                                              payment.failure  → payment failed or declined
                                              payment.cancel   → user cancelled (or closed modal)
                                              payment.pending  → async payment flow (e.g. waiting for bank)
```

The SDK appends `embedded=true` to the checkout URL automatically. The payment UI detects this flag and fires `window.parent.postMessage` instead of performing a full-page redirect.

<Warning>
  The iframe `src` carries the **checkout session token**, never your merchant `apiKey`. The `apiKey` is a long-lived bearer secret with full account access and must stay on your server. See [Mint a Checkout Session Token](/ipg/iframe-checkout/checkout-session-token) for the security model.
</Warning>

## postMessage Event Flow

The lifecycle of an embedded checkout session, from server-side preparation through completion:

<Steps>
  <Step title="Server creates the payment request">
    Your backend calls `POST /payment-requests` with `X-API-Key` and receives the request `id`. See [Create a Payment Request](/ipg/iframe-checkout/create-payment-request).
  </Step>

  <Step title="Server mints a checkout session token">
    Your backend calls `POST /payment-requests/{id}/checkout-session` with `X-API-Key`. The response contains a 15-minute scoped token. See [Mint a Checkout Session Token](/ipg/iframe-checkout/checkout-session-token).
  </Step>

  <Step title="Server returns { requestId, token } to the browser">
    Your own authenticated endpoint hands the values to the page that will host the SDK. Your `apiKey` never leaves the server.
  </Step>

  <Step title="Merchant page loads SDK script">
    Add the SDK `<script>` tag (or load it dynamically). The global `CaiboCheckout` object becomes available.
  </Step>

  <Step title="CaiboCheckout.init() creates iframe">
    Your code calls `CaiboCheckout.init({ paymentUrl: '.../main?requestId=…&token=…', ... })`.
  </Step>

  <Step title="Checkout UI renders inside iframe">
    The Caibo payment page reads `token` from the URL, stores it in `sessionStorage`, and uses it as the `X-Checkout-Token` header on every API call from that point on.
  </Step>

  <Step title="payment.ready → onReady callback">
    The SDK forwards the ready event to your `onReady` handler.
  </Step>

  <Step title="Customer enters card & submits payment">
    Card data and any 3-D Secure challenge happen entirely inside the iframe — never on your domain.
  </Step>

  <Step title="3DS challenge (if required) — inside iframe">
    Authentication navigates within the iframe. The final authentication result is delivered via `postMessage`.
  </Step>

  <Step title="payment.success / payment.failure → callback">
    The terminal event is forwarded to `onSuccess` or `onFailure` with the result payload.
  </Step>

  <Step title="SDK auto-calls destroy()">
    The iframe (or modal overlay) is removed and listeners are cleaned up automatically.
  </Step>
</Steps>

## Why Embedded?

<CardGroup cols={2}>
  <Card title="No full-page redirect" icon="window">
    The customer stays on your page; only the iframe content changes.
  </Card>

  <Card title="Card data isolation" icon="shield-check">
    Raw card data lives only inside the Caibo-hosted iframe — keeping your PCI scope minimal.
  </Card>

  <Card title="Native 3DS support" icon="lock">
    3-D Secure flows happen seamlessly inside the iframe with no extra code on your side.
  </Card>

  <Card title="Works with Apple/Google Pay" icon="credit-card">
    Wallet payments work normally inside the iframe; no extra configuration required.
  </Card>
</CardGroup>

## Next Steps

1. [Create a Payment Request](/ipg/iframe-checkout/create-payment-request) — obtain the `requestId` you'll pass to the SDK.
2. [Mint a Checkout Session Token](/ipg/iframe-checkout/checkout-session-token) — exchange your `apiKey` for a short-lived, scoped token.
3. [Quick Start — Inline & Modal](/ipg/iframe-checkout/quick-start) — copy a minimal working integration.
4. [SDK API Reference](/ipg/iframe-checkout/sdk-api-reference) — review every option and event payload.
