Checkout iframe 集成

​

适用场景

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

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

​

接入原则

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

​

推荐接入地址

https://checkout.stablepay.co/#/pay/cs_demo_123456/tk_demo_abcdef?lng=en

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

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

​

嵌入示例

<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 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
• 宿主页面中的布局、尺寸和滚动行为由接入方自行控制
• 建议预留足够空间，避免在关键付款步骤中出现裁切或双层滚动

​

安全与网关要求

frame-src https://checkout.stablepay.co;
child-src https://checkout.stablepay.co;

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

allow-scripts allow-forms allow-same-origin allow-popups allow-top-navigation-by-user-activation

​

兼容性说明

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

​

联调验收项

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

​

方案边界

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

​

相关页面

• 集成前准备
• Webhook 通知
• 稳定币收银台