Skip to main content
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
Use the full checkout URL returned when the transaction is created directly as your iframe src. 
https://checkout.stablepay.co/#/pay/cs_demo_123456/tk_demo_abcdef?lng=en
For example, the create transaction API may return: 
{
  "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: 
<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: 
<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: 
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: 
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 with your backend order-state handling.
Last modified on June 4, 2026