Iframe embedding

Before you start

⚠️

Origin allow-list required

By default the checkout responds with Unauthorized — this page cannot be embedded from this origin when loaded inside an <iframe>. Send us the origin (or list of origins) you plan to embed from and we'll allow them.

📘

Same customization as the standalone checkout

Form appearance, locale, payment methods and branding are configured the same way as the standalone checkout — see Hosted Checkout customization.

Embedding

<iframe
  src="https://checkout.carusell.world/s/{sessionId}"
  width="100%"
  height="720">
</iframe>

Inside an iframe:

• All outbound links open in a new tab.
• The Back to store button emits a postMessage instead of navigating.

Listening to events

The iframe posts messages to the parent window. Every message shares the same envelope; only payload varies between events:

{
  type: string;       // event identifier — see the Events section
  sessionId: string;  // checkout session the form is rendering
  intentId: string;   // intent the session belongs to
  payload?: object;   // event-specific, see each event
}

PaymentInfo is used as the payload by several events:

{
  paymentId: string;
  paymentMethod: FormPaymentMethodType;  // e.g. "CARD"
  paymentStatus: PaymentStatus;          // e.g. "ACCEPTED"
}

Events

Every event carries sessionId and intentId at the top level. Only payload varies between events.

Examples

{
  "type": "PAYMENT_ATTEMPT_SUCCESS",
  "sessionId": "IS313605683903180800",
  "intentId": "313605683324366848",
  "payload": {
    "paymentId": "313631993211891712",
    "paymentMethod": "CARD",
    "paymentStatus": "ACCEPTED"
  }
}

{
  "type": "PAYMENT_ATTEMPT_FAILED",
  "sessionId": "IS313639612777435136",
  "intentId": "313639612693549056",
  "payload": {
    "paymentMethod": "CARD",
    "reason": "FX rate expired or not found for payment method BankCardKZ in session IS313639612777435136"
  }
}