> ## 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 集成

> 如何将 StablePay Checkout 以纯 iframe 方式嵌入到网页、弹窗或抽屉中，以及这类集成方式的边界与注意事项。

本页说明如何通过纯 `iframe` 嵌入方式，将 StablePay Checkout 集成到第三方网站中。

在该模式下，嵌入的 checkout 页面负责展示付款流程并处理用户在 iframe 内的操作；支付结果同步仍应由服务端业务流程和 Webhook 驱动，而不是依赖父子页面前端通信。

## 适用场景

适合以下场景：

* 希望将 StablePay Checkout 直接嵌入页面、弹窗或抽屉中
* 用户在嵌入页内完成完整付款流程
* 商户通过后端状态流转、订单系统和 Webhook 处理付款结果

不适合以下场景：

* 父页面需要实时感知付款成功或失败
* 父页面需要自动关闭弹窗、刷新订单状态或触发额外前端联动
* 需要父子页面之间通过 `postMessage` 进行通信

## 接入原则

1. 接入方负责渲染 `iframe`
2. `iframe src` 应使用创建交易时返回的完整 checkout URL
3. 不要在前端自行拼接、推导或改写 checkout 路由参数
4. 当前 checkout 页面使用 Hash 路由，正式接入时必须保留 `#/`
5. 付款结果确认请使用服务端状态与 Webhook，不要只依赖前端展示结果

## 推荐接入地址

推荐将创建交易时返回的完整 checkout 地址直接作为 `iframe src` 使用。

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

例如，创建交易接口返回：

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

接入要求：

* 接收到完整 checkout URL 后，直接原样放入 `iframe src`
* 地址中的 `#/`、语言参数和其他业务参数都必须原样保留
* 不建议接入方自行改写、裁剪或重新拼接路由

## 嵌入示例

标准示例：

```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>
```

容器示例：

```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>
```

## 接入方开发要求

* 建议为 `iframe` 设置 `border: 0`
* 宿主页面中的布局、尺寸和滚动行为由接入方自行控制
* 建议预留足够空间，避免在关键付款步骤中出现裁切或双层滚动

## 安全与网关要求

如果宿主页面启用了 CSP，需要允许 checkout 域名被嵌入，例如：

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

在 checkout 服务部署链路上，不应由网关、CDN 或 ingress 层额外引入以下限制：

* `X-Frame-Options: DENY`
* 会拦截 iframe 嵌入的严格 `frame-ancestors` 策略

如果宿主页面必须使用 `sandbox`，建议至少放开以下能力：

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

如果没有强制的 sandbox 要求，建议不要启用，以减少兼容性风险。

## 兼容性说明

* 桌面浏览器在纯嵌入展示场景下通常兼容性良好
* 在移动端，部分钱包内置浏览器可能限制 deep link 拉起行为
* 如果某些移动钱包无法在 iframe 内正常打开，建议改为新窗口或全页打开 checkout
* 本页不展开 iframe 之外的钱包专项兼容处理

## 联调验收项

建议在联调阶段至少验证以下内容：

1. checkout 页面可以在 iframe 内正常加载
2. 二维码、金额和地址信息展示正常
3. 复制类操作可以正常执行
4. PC 端付款流程表现正常
5. 手机端付款流程表现正常
6. 结果页可以在 iframe 内正常展示
7. 宿主页面浏览器控制台中未出现 iframe 拦截相关报错

## 方案边界

* 本方案是纯嵌入展示方案
* 不包含父子页面回调能力
* 不包含支付状态实时前端通知能力
* 不包含自动关闭弹窗或自动跳转商户页能力

如需确定订单最终结果，请结合 [Webhook 通知](/zh/api/webhook-notifications) 和服务端订单状态处理。

## 相关页面

* [集成前准备](/zh/api/getting-started)
* [Webhook 通知](/zh/api/webhook-notifications)
* [稳定币收银台](/zh/product/Stablecoin-Checkout)