Skip to main content

​
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).
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.
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 for the security model.

​
postMessage Event Flow

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

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.
2

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.
3

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.
4

Merchant page loads SDK script

Add the SDK <script> tag (or load it dynamically). The global CaiboCheckout object becomes available.
5

CaiboCheckout.init() creates iframe

Your code calls CaiboCheckout.init({ paymentUrl: '.../main?requestId=…&token=…', ... }).
6

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.
7

payment.ready → onReady callback

The SDK forwards the ready event to your onReady handler.
8

Customer enters card & submits payment

Card data and any 3-D Secure challenge happen entirely inside the iframe — never on your domain.
9

3DS challenge (if required) — inside iframe

Authentication navigates within the iframe. The final authentication result is delivered via postMessage.
10

payment.success / payment.failure → callback

The terminal event is forwarded to onSuccess or onFailure with the result payload.
11

SDK auto-calls destroy()

The iframe (or modal overlay) is removed and listeners are cleaned up automatically.

​
Why Embedded?

No full-page redirect

The customer stays on your page; only the iframe content changes.

Card data isolation

Raw card data lives only inside the Caibo-hosted iframe — keeping your PCI scope minimal.

Native 3DS support

3-D Secure flows happen seamlessly inside the iframe with no extra code on your side.

Works with Apple/Google Pay

Wallet payments work normally inside the iframe; no extra configuration required.

​
Next Steps

  1. Create a Payment Request — obtain the requestId you’ll pass to the SDK.
  2. Mint a Checkout Session Token — exchange your apiKey for a short-lived, scoped token.
  3. Quick Start — Inline & Modal — copy a minimal working integration.
  4. SDK API Reference — review every option and event payload.