本页内容
托管收银台
将客户重定向到托管收银台，或以受限 iframe 嵌入付款页，然后依据带签名的确认 webhook 履约订单。
把 POST /v1/invoices 返回的 payment_url 作为标准收银台 URL。同一个 URL 支持两种展示方式——整页重定向和嵌入式 iframe。
除 Telegram 机器人外，两种展示方式适用于所有渠道。在 Telegram 机器人项目中，同一个 payment_url 打开的是 Paymos 机器人——那里没有可供重定向或嵌入的托管收银台页面。
重定向模式
重定向模式是最简单的集成方式。服务器创建账单后，把客户引导到 payment_url：
<a href="https://checkout.paymos.io/invoice/inv_xxx">Pay invoice</a>
客户在 Paymos 托管页面完成付款。你的服务器只有在收到并验证带签名的 webhook 事件后才履约订单。
嵌入模式
嵌入模式使用同一个 payment_url，加上 ?embed=true。当你的服务器已经负责创建账单、只想把托管收银台 UI 放进自己页面时使用：
<iframe
src="https://checkout.paymos.io/invoice/inv_xxx?embed=true"
title="Paymos checkout"
allow="clipboard-write"
sandbox="allow-scripts allow-same-origin allow-forms"
style="display:block;width:100%;max-width:460px;height:min(90vh,900px);border:0;"
></iframe>
嵌入事件
收银台 iframe 向父页面发送 postMessage 传输事件：
| 事件 | 含义 |
|---|---|
paymos:succeeded |
收银台到达 paid 或 paid_over。 |
paymos:failed |
收银台到达终态失败，如 underpaid、expired 或 cancelled。 |
paymos:close |
客户在嵌入式收银台内点击了关闭/返回操作。 |
父页面必须同时校验发送方 origin 和 iframe 来源：
const iframe = document.querySelector('#paymos-checkout');
window.addEventListener('message', (event) => {
if (event.origin !== 'https://checkout.paymos.io') return;
if (event.source !== iframe.contentWindow) return;
if (!event.data || typeof event.data !== 'object') return;
switch (event.data.type) {
case 'paymos:succeeded':
console.log('Payment UI succeeded:', event.data.invoice_id);
break;
case 'paymos:failed':
console.warn('Payment UI failed:', event.data.reason);
break;
case 'paymos:close':
iframe.remove();
break;
}
});
把这些事件当作 UX 提示，而不是付款凭证。可以用它们驱动加载动画、跳转和统计——但绝不要基于一条 postMessage 发货、入账或把订单标记为已支付。postMessage 极易伪造：与客户同源的任何页面都能发送假的 paymos:succeeded。结算只由带签名的服务端 webhook 确认——这是履约的唯一事实来源。
安全模型
推荐的 iframe sandbox 刻意保持最小：
- —
allow-scripts是收银台交互、API 调用、计时器、复制按钮和实时状态更新所必需的。 - —
allow-same-origin让 Paymos 托管收银台以自己的 origin 运行，而不是不透明的 sandbox origin。 - —
allow-forms允许收银台内的正常表单交互。 - —不设置
allow-top-navigation，iframe 因此无法导航商户页面。 - —不设置
allow-popups，因为收银台不需要打开额外的浏览器窗口。
什么时候改用 Low-Code SDK
当你希望 Paymos 从浏览器端配置创建账单、渲染付款按钮、管理弹窗生命周期、校验 iframe 消息并派发 paymos:* CustomEvent 时，使用 Low-Code SDK。
当你的后端已经负责创建账单、只需要把托管收银台 UI 放进页面时，使用手动 iframe 嵌入。