Skip to Content
结账概览

结账 概览

托管结账是买家实际发送资金的页面。你不需要自己渲染资产选择 器、充值地址或二维码 — SDK 会打开我们的页面（地址为 https://checkout.infraio.xyz/<session_key>），UI 由我们负责。

三种模式

居中的浮层弹窗，默认约 560×780。商店页面保持不动。付款后弹窗 关闭时触发 onSuccess。默认模式。

Popup

硬跳转到结账页。适合会拦截弹窗的浏览器，或浮层体验生硬的移动 端网页。买家通过会话中的 success_url / cancel_url 返回。

Redirect

嵌入你页面内的 iframe。适合你想端到端掌控布局、不希望出现上下 文切换的场景。通过 postMessage 自动调整大小。

Embed

选择模式的经验法则

如果……使用
桌面端网页、默认电商场景Popup
移动端网页Redirect（弹窗 + 移动端 = 体验差）
CSP 限制严格的管理后台Redirect
App 内 webview / 原生页面内结账Embed
你想要完全自定义的买家流程，并使用白标页头Embed + hideHeader + 自行接入钱包连接

买家会看到什么

无论使用哪种模式，页面都会展示：

  1. 订单摘要（明细项、总额、币种）。如果你已经在自己一侧展示 过，可以用 hideSummary 隐藏。
  2. 资产选择器 — 列出你在商户设置中启用的链 × 资产组合。买家从 中选择一个。
  3. 充值地址 + 二维码 + 金额，针对所选组合生成。买家可以扫码、 连接钱包（WalletConnect 按钮），或使用你通过 SDK 预先接入的钱包 直接付款。
  4. 状态提示 — “Waiting for transfer”、“Tx detected (3/12 confirmations)”、“Paid”。
  5. Cancel 按钮（始终显示）→ 触发 onCancel。

自定义页面

选项方式限制
隐藏订单摘要SDK 上设置 hideSummary: true买家仍能在充值面板中看到总额
隐藏 InfraIO 页头SDK 上设置 hideHeader: true搭配 walletAddress 可实现完全白标
预先接入钱包walletAddress + walletChainId + onSignRequest跳过 WalletConnect 弹窗
语言SDK 上的 locale — 取值为 en、vi、ja、ko、es、pt-BR、ru、tr、zh-CN、zh-TW 之一会本地化结账页和退款页面（以及钱包连接弹窗）。未知值或省略 → 回退到 en
Logo、品牌色商户仪表板 → Branding全局生效，不按会话单独设置

返回 URL 的行为

在 redirect 模式下，买家总会返回以下两者之一：

  • 会话中的 success_url（支付结算成功时）
  • 会话中的 cancel_url（取消 / 放弃时）
  • 如果你没有设置这些，SDK 会回退到打开结账页的那个页面，并附加 ?session_id=…&status=success|cancel

在 popup 和 embed 模式下不会发生页面跳转 — 控制权通过 onSuccess / onCancel 回到你的页面。用它们来决定接下来展示 什么 UI。

CSP 与嵌入

如果你使用 embed 模式，你的 CSP 必须在 frame-src 中放行我们 的 origin：

Content-Security-Policy:
  frame-src https://checkout.infraio.xyz https://checkout-dev.infraio.xyz;

这个 iframe 携带权限策略 allow="payment; clipboard-write" — 它 只能调用 Payment Request API 和写入剪贴板，仅此而已。它没有加 上 HTML 的 sandbox：结账页是一个完整的钱包连接应用，其 postMessage 安全机制（双方都做 origin 校验）以及第三方钱包 SDK （WalletConnect、Coinbase、MetaMask）都需要一个真正的同源脚本执行 上下文，所以加上 HTML 的 sandbox 属性会破坏钱包连接功能，换来的 隔离收益却微乎其微。隔离性反而来自跨源边界、严格的 postMessage origin 校验，以及你的 frame-src CSP。

移动端注意事项

移动端 Safari 会非常积极地拦截弹窗。如果你的流量以移动端为主，默 认使用 mode: "redirect"。在小屏幕上，弹窗浮层还会遮住键盘区域 — 用于输入金额还好，用于选择资产就比较别扭。

品牌定制（面向白标场景）

完全白标需要：

  1. SDK 上设置 hideHeader: true
  2. 预先接入 walletAddress（买家看不到 WalletConnect）
  3. 在商户仪表板的品牌设置中配置你的 Logo + 品牌色
  4. （可选）为结账页设置自定义域名 — 例如用 pay.your-shop.com 代替 checkout.infraio.xyz。CNAME 验证通过后，可在仪表板自助 配置。

下一步

支持的链与资产概览