> ## 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.
# 收银台集成 - 集成步骤
> 使用 Waffo 托管收银台完成支付集成的完整流程。
收银台（Checkout）是最简单的集成方式——将用户重定向到 Waffo 托管的支付页面，无需处理敏感卡信息。
本页包含**服务端**职责（创建订单、接收 Webhook 回调）与**前端**职责（解析 orderAction、跳转、iframe / window\.open / WebView 嵌入）。请按你的角色阅读对应部分。
## 工作流程
```mermaid theme={null}
sequenceDiagram
participant M as 商户服务端
participant W as Waffo
participant U as 用户
M->>W: 1. 创建订单 (API)
W-->>M: 2. 返回 orderAction
M->>U: 3. 重定向用户
U->>W: 4. 用户完成支付
W-->>M: 5. Webhook 通知
W->>U: 6. 重定向回商户
```
调用创建支付接口，获取响应中的 `orderAction`（JSON 字符串）。
先解析 `orderAction`，再根据 `actionType` 使用 `webUrl` 或 `deeplinkUrl`。用户将在 Waffo 收银台页面完成支付。
* **Webhook**（推荐）：Waffo 向 `notifyUrl` 发送支付结果通知
* **重定向**：支付成功跳转到 `successRedirectUrl`；预校验失败或支付失败跳转到 `failedRedirectUrl`；用户主动取消且不继续支付时跳转到 `cancelRedirectUrl`
* **主动查询**：调用查询支付接口
重定向仅表示用户回到了你的网站，不代表支付成功。始终以 Webhook 或主动查询的结果为准。
### 获取收银台 URL
`orderAction` 是字符串形式的 JSON。先解析它，再根据 `actionType` 选择 URL：
不同的 `payMethodType` / `payMethodName` 会影响用户是否先进入 Waffo 的支付方式选择页。详见 [收银台集成 - 自定义选项](/docs/zh/developer-docs/integration/checkout/customization)。
```typescript theme={null}
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`，否则微信支付会失败
```html theme={null}
```
### 宽度自适应
禁止使用固定宽度（如 `width: 700px`），否则在不同设备上内容会被截断。建议使用自适应布局：
```css theme={null}
.checkout-container {
overflow: scroll;
height: calc(100vh - 40px);
}
```
### 已知限制
* **Apple Pay**：iframe 场景必须使用 Waffo 前端 SDK，并提前联系 Waffo 技术支持完成域名验证和报备。不要直接用普通 iframe 加载 `orderAction.webUrl`。参见 [Apple Pay 集成](/docs/zh/developer-docs/integration/apple-pay/overview#方式三通过-iframe-加载-waffo-apple-pay-收银台)
* **JKOPAY**：不支持 iframe 加载
* **手机端**：检查 iframe 是否固定大小导致显示为 PC 横屏页面
* 更多按支付方式或支付方式类型触发的限制，参见 [支付方式集成注意事项](/docs/zh/developer-docs/tools-and-references/references/payment-method-integration-notes)
***
## `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 等限制，参见 [支付方式集成注意事项](/docs/zh/developer-docs/tools-and-references/references/payment-method-integration-notes)