> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout iframe Integration

> How to embed StablePay Checkout in a webpage, modal, or drawer using a pure iframe integration pattern, including limits and implementation notes.

This page explains how to integrate StablePay Checkout into a third-party website using a pure `iframe` embedding approach.

In this mode, the embedded checkout page is responsible for rendering the payment flow and handling user actions inside the iframe. Payment result handling should still be driven by your backend workflow and Webhooks rather than parent-child frontend messaging.

## When to use it

This approach is a good fit when:

* You want to embed StablePay Checkout directly into a page, modal, or drawer
* The payer completes the full payment flow inside the embedded frame
* Your backend, order system, and Webhooks handle payment outcomes

This approach is not a good fit when:

* The parent page must detect payment success or failure in real time
* The parent page must automatically close the modal, refresh order status, or trigger extra frontend actions
* You need `postMessage` communication between the parent page and the embedded checkout

## Integration principles

1. The integrator is responsible for rendering the `iframe`
2. Use the full checkout URL returned when the transaction is created
3. Do not manually infer, compose, or rewrite checkout routing parameters on the frontend
4. The checkout page currently uses Hash routing, so the `#/` segment must be preserved
5. Use backend state and Webhooks to confirm payment outcomes instead of relying on frontend display alone

## Recommended URL format

Use the full checkout URL returned when the transaction is created directly as your `iframe src`.

```text theme={"system"}
https://checkout.stablepay.co/#/pay/cs_demo_123456/tk_demo_abcdef?lng=en
```

For example, the create transaction API may return:

```json theme={"system"}
{
  "payment_url": "https://checkout.stablepay.co/#/pay/cs_demo_123456/tk_demo_abcdef?lng=en"
}
```

Integration rules:

* Once you receive the full checkout URL, place it directly into the `iframe src`
* Preserve the `#/` segment, language parameter, and any other business parameters exactly as returned
* Do not trim, reconstruct, or rewrite the route on the integrator side

## Embedding example

Standard example:

```html theme={"system"}
<iframe
  src="https://checkout.stablepay.co/#/pay/cs_demo_123456/tk_demo_abcdef?lng=en"
  width="100%"
  style="border:0;background:#fff;"
  referrerpolicy="strict-origin-when-cross-origin"
  allow="clipboard-write"
></iframe>
```

Container example:

```html theme={"system"}
<div style="margin: 0 auto;">
  <iframe
    src="https://checkout.stablepay.co/#/pay/cs_demo_123456/tk_demo_abcdef?lng=en"
    width="100%"
    style="border:0;background:#fff;"
    referrerpolicy="strict-origin-when-cross-origin"
    allow="clipboard-write"
  ></iframe>
</div>
```

## Integrator requirements

* Set `border: 0` on the `iframe`
* The host page is responsible for layout, sizing, and scroll behavior
* Leave enough space for key payment steps to avoid clipping or double-scroll issues

## Security and gateway requirements

If your host page uses CSP, allow the checkout domain to be embedded, for example:

```text theme={"system"}
frame-src https://checkout.stablepay.co;
child-src https://checkout.stablepay.co;
```

Do not introduce the following restrictions on the checkout delivery path through gateways, CDNs, or ingress layers:

* `X-Frame-Options: DENY`
* restrictive `frame-ancestors` policies that block iframe embedding

If the host page must use `sandbox`, allow at least:

```text theme={"system"}
allow-scripts allow-forms allow-same-origin allow-popups allow-top-navigation-by-user-activation
```

If sandbox is not required by policy, leaving it disabled is generally safer for compatibility.

## Compatibility notes

* Desktop browsers are generally compatible with this pure embedded display pattern
* On mobile, some in-wallet browsers may restrict deep-link behavior
* If a specific mobile wallet cannot open correctly inside the iframe, use a new window or full-page checkout instead
* This page does not cover wallet-specific handling outside the pure iframe pattern

## Validation checklist

During integration testing, validate at least the following:

1. The checkout page loads correctly inside the iframe
2. QR code, amount, and payment address display correctly
3. Copy actions work as expected
4. The desktop payment flow behaves correctly
5. The mobile payment flow behaves correctly
6. Result pages can be displayed correctly inside the iframe
7. No iframe blocking errors appear in the host page browser console

## Solution boundaries

* This is a pure embedded display solution
* It does not include parent-child page callback capabilities
* It does not include real-time frontend payment status notifications
* It does not include automatic modal closing or automatic redirect back to the merchant page

To determine the final order outcome, combine [Webhook Notifications](/en/api/webhook-notifications) with your backend order-state handling.

## Related pages

* [Pre-Integration Setup](/en/api/getting-started)
* [Webhook Notifications](/en/api/webhook-notifications)
* [Stablecoin Checkout](/en/product/Stablecoin-Checkout)