跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://waffo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

收银台（Checkout）是最简单的集成方式——将用户重定向到 Waffo 托管的支付页面，无需处理敏感卡信息。

​
工作流程

1

服务端创建订单

调用创建支付接口，获取响应中的 orderAction（JSON 字符串）。
2

重定向用户

先解析 orderAction，再根据 actionType 使用 webUrl 或 deeplinkUrl。用户将在 Waffo 收银台页面完成支付。
3

处理结果

  • Webhook（推荐）：Waffo 向 notifyUrl 发送支付结果通知
  • 重定向：支付成功跳转到 successRedirectUrl；预校验失败或支付失败跳转到 failedRedirectUrl；用户主动取消且不继续支付时跳转到 cancelRedirectUrl
  • 主动查询：调用查询支付接口
重定向仅表示用户回到了你的网站，不代表支付成功。始终以 Webhook 或主动查询的结果为准。

​
获取收银台 URL

orderAction 是字符串形式的 JSON。先解析它，再根据 actionType 选择 URL： 
const orderAction = JSON.parse(response.data.orderAction);
const checkoutUrl = orderAction.actionType === 'DEEPLINK'
  ? orderAction.deeplinkUrl
  : orderAction.webUrl;

​
支付方式前置配置

  • 微信支付：如果生产环境需要启用微信支付，请提前将生产域名提交给 Waffo，由 Waffo 向渠道报备

​
iframe 嵌入注意事项

如果通过 iframe 嵌入 Waffo 收银台，需要注意以下问题：

​
必须配置

  • allow="payment" 属性：iframe 标签必须添加 allow="payment"，否则 Google Pay 等支付方式在 Android 手机上无法使用
  • Referrer Policy：必须设置为 strict-origin-when-cross-origin，否则微信支付会失败
<head>
  <meta name="referrer" content="strict-origin-when-cross-origin">
</head>

<iframe src="https://cashier.waffo.com/..." allow="payment"></iframe>

​
宽度自适应

禁止使用固定宽度（如 width: 700px），否则在不同设备上内容会被截断。建议使用自适应布局： 
.checkout-container {
  overflow: scroll;
  height: calc(100vh - 40px);
}

​
已知限制

  • Apple Pay：原生 Apple Pay 在 iframe 内无法使用（同源策略限制），不仅 H5 页面，PC 端 iframe 也受影响。**Waffo 提供 JS SDK 方案处理该场景，使用前需提前向 Waffo 报备域名。**App 的 WebView 不受此 iframe 限制
  • JKOPAY：不支持 iframe 加载
  • 手机端：检查 iframe 是否固定大小导致显示为 PC 横屏页面
  • 更多按支付方式或支付方式类型触发的限制，参见 支付方式集成注意事项

​
window.open 嵌入注意事项

使用 window.open 打开收银台时：
  • 同步调用可以：点击事件中直接 window.open() 没有问题
  • 异步调用会被拦截：如果在 await 之后调用 window.open()，浏览器会拦截弹窗。解决方法：先 window.open() 打开空白页，异步获取 URL 后再赋值；或增加一个确认弹窗让用户手动点击打开
  • Apple 移动端：用户手势检测比较严格，异步打开几乎必定被拦截

​
App WebView 集成注意事项

商户 App 通过 WebView 加载收银台时：
  • 外部跳转能力：确认 App 和 WebView 允许打开外部 App 或外部浏览器页面。部分钱包会通过 deeplink 或外部页面完成授权，如果限制了会导致支付无法继续
  • 下载与复制能力：WebView 默认不一定支持文件下载、复制或长按保存。QR、OTC、银行转账等支付方式可能依赖这些能力
  • 回跳 URL 保真：原生 App 与 WebView 之间传递 URL 时，不要改写 URL 或丢弃 query 参数。部分支付方式会在回跳 URL 上追加必要参数
  • userTerminal：传 APP 而非 WEB，以获取适合 App 端的跳转链接
  • 支付方式特殊限制：PayPay Smart Payment、Google Pay、Apple Pay、JKOPAY 等限制，参见 支付方式集成注意事项