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 embedded checkout SDK targets all evergreen desktop and mobile browsers. The matrix below summarizes support for the SDK itself and for the wallet payment methods that work inside the iframe.Browser Compatibility
| Browser | Embedded Checkout | Apple Pay | Google Pay |
|---|---|---|---|
| Chrome 90+ | Yes | No (iOS/macOS Safari only) | Yes |
| Safari 14+ | Yes | Yes | Yes |
| Firefox 88+ | Yes | No | Yes |
| Edge 90+ | Yes | No | Yes |
Apple Pay availability follows Apple’s platform restrictions and is independent of the SDK — it requires Safari on iOS or macOS.
Important Notes
3DS flows
3DS flows
3-D Secure authentication navigates within the iframe — this is the expected behavior. The final authentication result is delivered to the parent window via
postMessage, so your onSuccess / onFailure callbacks fire as usual.Apple Pay / Google Pay
Apple Pay / Google Pay
Both wallets work normally inside the iframe; no extra configuration is required on your side. Make sure your domain is registered with the wallet provider as part of your merchant onboarding.
Non-embedded mode
Non-embedded mode
Opening the checkout URL directly (without the SDK) behaves as before — full-page redirects are used. The
embedded=true flag is appended only when launched through CaiboCheckout.init().Modal scroll lock
Modal scroll lock
While the modal is open, the SDK sets
document.body.style.overflow = 'hidden' to prevent background scrolling. The original value is restored automatically when destroy() runs (either via a terminal event or a manual call).CSP / Security
CSP / Security
The SDK accepts
postMessage from the checkout origin only. For stricter Content Security Policy setups, configure frame-ancestors on the backend so only your approved origins can embed the iframe.Checkout session token expiry
Checkout session token expiry
Tokens are valid for 15 minutes from issuance. If a customer leaves the page open past that, the iframe will start receiving
401 Unauthorized for every API call and the checkout UI will appear stuck. Mint a fresh token server-side and re-open the iframe to recover. See Mint a Checkout Session Token.Troubleshooting Quick Checks
Iframe blank / white page
Open DevTools inside the iframe. The most common causes are: (1)
paymentUrl is missing the token= parameter, (2) the token expired (15-minute TTL — check the Network tab for 401s), or (3) originDomain on the payment request does not match the page hosting the iframe.No callbacks fire
Confirm the SDK script loaded and that
CaiboCheckout.init() returned without error. Check the browser console for cross-origin warnings.403 Forbidden in the iframe
The token is being sent to an endpoint that is not on the token’s allow-list, or the
paymentRequestId in the URL/query does not match the bound id. Mint a token bound to the correct payment request.Modal cannot be closed
Backdrop click, ×, and Esc all fire
onCancel. If you bound onCancel to a no-op, the modal will still tear down via destroy().Wallet button missing
Apple Pay only renders on Safari (iOS / macOS). Google Pay needs an HTTPS context and a supported Chromium-based browser.
Deprecation warning about apiKey
The checkout page emits a
console.warn if the iframe URL still carries apiKey=. Migrate to checkout session tokens — the apiKey is a long-lived secret and must not appear in browser URLs.Next Steps
- How Embedded Checkout Works — architecture and event flow.
- SDK API Reference — full option and payload list.