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

# SDK API Reference

> Complete reference for the Caibo embedded checkout SDK: CaiboCheckout.init() options, CaiboCheckout.destroy(), and event payloads.

# Overview

This page documents every method, option, and event payload exposed by the embedded checkout SDK.

## `CaiboCheckout.init(options)`

Initializes the checkout iframe and binds event listeners.

### Options

| Option        | Type       | Required        | Default    | Description                                                                                                                                 |
| ------------- | ---------- | --------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`        | `string`   | —               | `'inline'` | Display mode: `'inline'` or `'modal'`.                                                                                                      |
| `paymentUrl`  | `string`   | **Required**    | —          | Full checkout URL: `.../main?requestId=…&token=…` where `token` is a [checkout session token](/ipg/iframe-checkout/checkout-session-token). |
| `containerId` | `string`   | **Inline only** | —          | ID of the `<div>` to mount the iframe into.                                                                                                 |
| `width`       | `string`   | —               | `'480px'`  | Modal width (modal) or iframe width (inline).                                                                                               |
| `height`      | `string`   | —               | `'700px'`  | CSS height of the iframe.                                                                                                                   |
| `onSuccess`   | `function` | —               | —          | Called when payment completes successfully.                                                                                                 |
| `onFailure`   | `function` | —               | —          | Called when payment fails or is declined.                                                                                                   |
| `onCancel`    | `function` | —               | —          | Called when user cancels or closes the modal.                                                                                               |
| `onPending`   | `function` | —               | —          | Called for async payment flows (e.g. waiting for bank confirmation).                                                                        |
| `onReady`     | `function` | —               | —          | Called when the checkout page has loaded inside the iframe.                                                                                 |

<Note>
  `containerId` is required only for `mode: 'inline'`. In `'modal'` mode the SDK creates its own overlay attached to `document.body`.
</Note>

<Warning>
  `paymentUrl` must carry a short-lived `token`, not your `apiKey`. The merchant `apiKey` is a long-lived secret and must stay on your server. Mint a token with [`POST /payment-requests/{id}/checkout-session`](/ipg/iframe-checkout/checkout-session-token) and pass the response's `token` as the `token` query parameter.
</Warning>

## `CaiboCheckout.destroy()`

Removes the iframe (inline) or the overlay (modal), cleans up all event listeners, and restores `document.body` scroll. Called **automatically** on `success`, `failure`, and `cancel`. Call it manually only to close programmatically (for example, from a custom abort button).

```js theme={null}
CaiboCheckout.destroy();
```

## Event Payload

All callbacks receive a single `data` object. The shape depends on the event:

| Event             | Payload                         | Description                          |
| ----------------- | ------------------------------- | ------------------------------------ |
| `payment.success` | `{ url, requestId, paymentId }` | Redirect URL, request & payment IDs. |
| `payment.failure` | `{ url, requestId, paymentId }` | Failure URL with identifiers.        |
| `payment.pending` | `{ url, requestId }`            | Waiting URL for async flows.         |
| `payment.cancel`  | `{}`                            | User-initiated cancellation.         |
| `payment.ready`   | `{}`                            | Checkout page loaded.                |

### Example Payloads

```js theme={null}
// payment.success
{ url: 'https://merchant.com/success', requestId: '12345', paymentId: '67890' }

// payment.failure
{ url: 'https://merchant.com/failure', requestId: '12345', paymentId: '67890' }

// payment.pending
{ url: 'https://merchant.com/waiting', requestId: '12345' }

// payment.cancel  (user-initiated)
{}
```

## Lifecycle Summary

<Steps>
  <Step title="init">
    Call `CaiboCheckout.init(options)` to render the iframe and start listening for `postMessage` events.
  </Step>

  <Step title="onReady">
    Fired once the checkout page has rendered inside the iframe.
  </Step>

  <Step title="Terminal event">
    Exactly one of `onSuccess`, `onFailure`, `onPending`, or `onCancel` is fired.
  </Step>

  <Step title="destroy (auto)">
    The SDK removes the iframe/overlay and cleans up listeners. Body scroll is restored.
  </Step>
</Steps>

## Next Steps

* [Framework Examples](/ipg/iframe-checkout/framework-examples) — React, Angular, Vue 3.
* [Browser Support & Notes](/ipg/iframe-checkout/browser-support) — compatibility matrix and security notes.