> ## 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 收银台绑卡
> 在 Waffo 收银台完成一次 CIT，并生成可用于后续 MIT 的银行卡 Token。
在 Waffo 收银台中完成一次持卡人发起交易（CIT），并将本次使用的银行卡转换为 Token，供后续商户发起交易（MIT）使用。商户页面和后端不接触明文卡信息。
## 适用场景
当你已经集成 Waffo 收银台，并希望在首次支付后继续发起以下扣款时，使用 Waffo 收银台绑卡：
* 按固定计划发起的 scheduled MIT
* 用户离线时发起的 unscheduled MIT
* 商户自行管理周期计划，并通过 `ONE_TIME_PAYMENT` 完成后续扣款
如果你需要在没有本次支付的情况下独立绑卡，或需要在自己的页面中设计绑卡界面，请使用[商户侧绑卡](/docs/zh/developer-docs/integration/tokenization/overview)。
## 完整时序
```mermaid theme={null}
sequenceDiagram
actor User as 用户
participant Merchant as 商户服务端
participant Waffo
participant Checkout as Waffo 收银台
participant Channel as 支付渠道
Merchant->>Waffo: POST /api/v1/order/create
setupFutureUsage=true
Waffo-->>Merchant: 创建订单响应
data.orderStatus + data.orderAction
Merchant-->>User: 跳转到 Waffo 收银台
User->>Checkout: 输入新卡并提交
Checkout->>Waffo: 提交支付方式
Waffo->>Channel: 发起 CIT
Channel-->>Waffo: 支付成功
Waffo->>Waffo: 为后续使用生成 Token
Waffo-->>Merchant: PAYMENT_NOTIFICATION Webhook
paymentInfo.userPaymentAccessToken
opt 主动查询支付结果
Merchant->>Waffo: POST /api/v1/order/inquiry
Waffo-->>Merchant: 订单查询响应
data.orderStatus + data.paymentInfo.userPaymentAccessToken
end
Merchant->>Merchant: 保存 Token
Note over Merchant,Waffo: 商户已通过 MIT 白名单准入
Merchant->>Waffo: POST /api/v1/order/create
userPaymentAccessToken + merchantInitiatedMode
Waffo-->>Merchant: 创建订单响应
data.orderStatus
Waffo->>Channel: 使用 Token 发起 MIT
Channel-->>Waffo: MIT 结果
Waffo-->>Merchant: PAYMENT_NOTIFICATION Webhook
MIT 结果
opt 主动查询 MIT 结果
Merchant->>Waffo: POST /api/v1/order/inquiry
Waffo-->>Merchant: 订单查询响应
data.orderStatus
end
```
## 与商户侧绑卡的区别
| 对比项 | Waffo 收银台绑卡 | 商户侧绑卡 |
| -------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| 入口 | `POST /api/v1/order/create`，设置 `paymentInfo.setupFutureUsage: true` | `POST /api/v1/tokenization/generate` + `sdk.tokenizationSubmit()` |
| 用户目标 | 完成支付，并为后续 MIT 生成 Token | 只绑定银行卡，不要求本次完成正常金额支付 |
| 卡信息页面 | Waffo 托管收银台 | 商户页面中的 `@waffo/payment-sdk` |
| 集成成本 | 较低；复用现有收银台支付流程，增加 `setupFutureUsage` 和 Token 结果处理 | 较高；需接入 Tokenization API、前端 SDK、0 元 CIT 验证及 Token 状态通知 |
| 首次验证 | 本次成功的 CIT 用于验证支付方式 | 先绑卡，再发起一笔 0 元 CIT；3DS 只可能出现在这笔 CIT 中 |
| Token 结果 | 从 `PAYMENT_NOTIFICATION` 或订单查询响应的 `paymentInfo.userPaymentAccessToken` 获取 | 通过 Generate 请求中的 `notifyUrl` 接收 `TOKENIZATION_NOTIFICATION` |
## 前置条件
* 你已完成[收银台集成](/docs/zh/developer-docs/integration/checkout/steps)。
* 订单使用 `ONE_TIME_PAYMENT`。
* 商户已开通支持 MIT 的银行卡支付方式。设置 `setupFutureUsage: true` 后，Waffo 只提供支持 MIT 的支付方式。
* 商户已通过 Waffo 的 MIT 白名单准入。未完成准入时不可发起 MIT。
* `userInfo.userId` 对同一用户保持稳定。后续使用 Token 时仍需传入同一个用户 ID。
## 集成步骤
调用[创建支付](/docs/api-reference/order-create/create-new-order)，在 `paymentInfo` 中设置 `setupFutureUsage: true`。
```json theme={null}
{
"paymentRequestId": "PAY_202609160001",
"merchantOrderId": "ORDER_202609160001",
"orderCurrency": "HKD",
"orderAmount": "100.00",
"orderDescription": "Initial payment with card binding",
"orderRequestedAt": "2026-09-17T02:00:00.000Z",
"notifyUrl": "https://merchant.example.com/webhooks/payment",
"successRedirectUrl": "https://merchant.example.com/payment/success",
"failedRedirectUrl": "https://merchant.example.com/payment/failed",
"merchantInfo": {
"merchantId": "YOUR_MERCHANT_ID"
},
"userInfo": {
"userId": "USER_001",
"userEmail": "user@example.com",
"userTerminal": "WEB",
"userCountryCode": "HKG"
},
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"setupFutureUsage": true
}
}
```
不要同时传入 `paymentInfo.setupFutureUsage` 和 `paymentInfo.userPaymentAccessToken`。前者表示创建新 Token，后者表示使用已有 Token。
按照普通收银台支付流程解析响应中的 `orderAction`，并将用户重定向到 Waffo 收银台。用户输入新卡并完成支付。
如果用户选择已有的已存卡，Waffo 会复用该卡，不会重复绑定同一张卡。
Waffo 收银台绑卡不会发送 `TOKENIZATION_NOTIFICATION`。支付成功后，Waffo 向创建订单时的 `notifyUrl` 发送 `PAYMENT_NOTIFICATION`。从 `result.paymentInfo.userPaymentAccessToken` 获取本次支付生成的 Token。
支付通知关键字段节选：
```json theme={null}
{
"eventType": "PAYMENT_NOTIFICATION",
"result": {
"paymentInfo": {
"userPaymentAccessToken": "TOKEN_xxxxxxxxxxxx"
}
}
}
```
请在支付成功后保存 `result.paymentInfo.userPaymentAccessToken`。如果支付通知未送达，可调用 [`POST /api/v1/order/inquiry`](/docs/api-reference/order-inquiry/order-inquiry)，传入 `paymentRequestId` 或 `acquiringOrderId`，并从响应中的相同字段获取 Token。例如：
```json theme={null}
{
"paymentRequestId": "PAY_202609160001"
}
```
不要等待 `TOKENIZATION_NOTIFICATION`。
只有已通过 Waffo MIT 白名单准入的商户才能发起 MIT。未完成准入时不可发起 scheduled 或 unscheduled MIT。
后续扣款时，将支付通知中的 Token 作为 `paymentInfo.userPaymentAccessToken`，并设置 `merchantInitiatedMode`。
```json theme={null}
{
"paymentRequestId": "MIT_202610160001",
"merchantOrderId": "ORDER_202610160001",
"orderCurrency": "HKD",
"orderAmount": "49.00",
"orderDescription": "Scheduled merchant-initiated payment",
"orderRequestedAt": "2026-10-16T02:00:00.000Z",
"notifyUrl": "https://merchant.example.com/webhooks/payment",
"merchantInfo": {
"merchantId": "YOUR_MERCHANT_ID"
},
"userInfo": {
"userId": "USER_001",
"userEmail": "user@example.com",
"userTerminal": "WEB"
},
"paymentInfo": {
"productName": "ONE_TIME_PAYMENT",
"userPaymentAccessToken": "TOKEN_xxxxxxxxxxxx",
"merchantInitiatedMode": "scheduled"
}
}
```
`merchantInitiatedMode` 支持：
* `scheduled`：按预先约定的固定计划扣款
* `unscheduled`：没有固定周期的商户发起扣款
## 常见问题
### 没有可用支付方式
设置 `setupFutureUsage: true` 后，Waffo 会过滤不支持 MIT 的支付方式。确认商户已开通支持 MIT 的银行卡合约；仍无可用方式时，请联系 Waffo 技术支持。
### 支付成功但暂未收到 Token
先确认是否已收到 `PAYMENT_NOTIFICATION`，并读取 `result.paymentInfo.userPaymentAccessToken`。如果支付通知未送达，调用订单查询获取同一字段。Waffo 收银台绑卡不会发送 `TOKENIZATION_NOTIFICATION`。
### 无法发起 MIT
确认商户已通过 Waffo MIT 白名单准入。未完成准入时，即使已经获得 Token，也不可发起 scheduled 或 unscheduled MIT。