Skip to main content

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.

​
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).
Merchant Page
├── Inline mode                          Modal mode
│   ├── <div id="caibo-checkout">        ├── SDK creates overlay on <body>
│   │     └── <iframe ...?embedded=true> │     └── <iframe ...?embedded=true>
│   │           └── Payment UI           │           └── Payment UI
│
└── postMessage events flow back to the parent window
      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.

​
postMessage Event Flow

The lifecycle of an embedded checkout session, from script load through completion:
1

Merchant page loads SDK script

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

CaiboCheckout.init() creates iframe

Your code calls CaiboCheckout.init(options) with the payment URL and callbacks.
3

Checkout UI renders inside iframe

The Caibo payment page is fetched and displayed inside the iframe.
4

payment.ready → onReady callback

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

Customer enters card & submits payment

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

3DS challenge (if required) — inside iframe

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

payment.success / payment.failure → callback

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

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. Quick Start — Inline & Modal — copy a minimal working integration.
  3. SDK API Reference — review every option and event payload.