> ## 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 的订阅 API 让 Waffo 自动续订，还是自己存 token、自己排期扣款。其中 Waffo 订阅里，续订又分「Waffo 来扣」和「支付方式一侧来扣」两种。接入步骤和字段细节见官网的[订阅集成指南](https://waffo.com/docs/zh/developer-docs/integration/subscription/overview.md)与[订阅支付方式对比](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/subscription-payment-methods.md)页。

## 我该用订阅 API，还是自己用 token 扣款？

按「谁管订阅」分，一共三种做法：

| 做法 | 谁管订阅 | 每期怎么扣款 | 用到的接口 |
| - | - | - | - |
| ① Waffo 托管续订 | Waffo | 用户首次授权后，Waffo 按周期自动扣款、自动重试 | `/api/v1/subscription/*` |
| ② 支付方式托管续订 | Waffo 订阅 API + 支付方式一侧 | 首次授权后由支付方式自己的周期扣款机制发起，Waffo 不触发 | `/api/v1/subscription/*` |
| ③ 商户自管订阅 | 你 | 你存下 token，按自己的排期发起商户发起扣款（MIT） | `/api/v1/order/create`，不使用 `/api/v1/subscription/*` |

①和②在 Waffo 官网里同属「Waffo 订阅」一种接入方式，对你来说接口是同一套，差别在于续订由谁来执行（见下一问）。③是另一种接入方式。

选择时先问自己三个问题：

| 问题 | 答案倾向 |
| - | - |
| 我想让 Waffo 管周期、重试、升降级、取消吗？ | 想 → ①或②；不想 → ③ |
| 我的用户主要用哪些支付方式？ | 卡、Apple Pay、Google Pay、PayPay 及其他主流钱包、Paidy 属于①；PIX 属于② |
| 我需要完全自己控制每期扣款时间和金额吗？ | 需要 → ③ |

具体某个支付方式能不能做订阅、支持到什么程度，以你合同配置和 `/api/v1/paymethodconfig/inquiry` 的返回为准。

## 「Waffo 托管续订」和「支付方式托管续订」有什么区别？

| 对比项 | Waffo 托管续订 | 支付方式托管续订 |
| - | - | - |
| 谁发起每期扣款 | Waffo | 支付方式一侧 |
| 典型支付方式 | 卡、Apple Pay、Google Pay、PayPay、其他主流钱包、Paidy | PIX |
| 付款优先 / 服务优先两种订阅模式 | 都支持 | 只支持服务优先 |
| 失败后的重试 | Waffo 按你合同的重试策略自动重试 | 按支付方式自己的重试规则，不支持商户定制 |
| 升降级、金额更新、延迟开始 | 支持 | 暂不支持（官网标注为即将支持） |
| 按期金额（`scheduledAmounts`） | 符合条件的订阅支持 | 不支持 |
| 试用期频率 | 可以与正式周期不同 | 必须与正式周期一致 |
| 扣款频率 | 按天 1–365、按周 1–4、按月 1 个月及以上（季度用 3，半年用 6，年用 12） | 只支持按周（每 1 周）和按月（每 1、3、6、12 个月）；不支持按天 |
| 商户侧取消 | 支持 | 支持 |

两者共用同一套订阅 API：创建、查询、取消、管理页、升降级、更新。创建订阅时都要传 `subscriptionManagementUrl`，状态变化和每期结果都通过 Webhook 通知你。

**付款优先和服务优先**是 Waffo 托管续订下的另一个选择，决定某期扣款失败后怎么办：

| | 付款优先 | 服务优先 |
| - | - | - |
| 当期扣款失败时 | 权益暂停 | 服务继续 |
| 之后各期 | 不再创建 | 照原计划创建 |
| 重试成功后下一期的计费基准 | 从重试成功时间重新开始 | 保持原计划基准 |
| 允许同时存在多笔未付账单 | 不允许 | 允许 |

接入前就要定下用哪种，并告知 Waffo。

## 支付方式一侧的订阅号和用户标识在哪看？

有些支付方式在自己一侧也会为订阅生成编号或用户标识。Waffo 在订阅接口里原样带回，方便你和支付方式一侧核对：

* `payMethodSubscriptionId`：支付方式一侧的订阅 ID。创建订阅的响应和 /api/v1/subscription/inquiry 都会返回。
* `paymentInfo.payMethodPublicUid`：用户在该支付方式上的公开用户 ID，在 /api/v1/subscription/inquiry 的 `paymentInfo` 里返回。

两个字段都是选填，只有支付方式一侧提供时才有值。管理订阅（查询、取消、恢复）仍然用 Waffo 的 `subscriptionId`。

## 想自己控制每期扣款（商户自管订阅），要做什么？

商户自管订阅不用订阅 API。每期你自己用已保存的 token 发起 MIT：

* 你自己负责：计费排期、订阅状态、失败重试、套餐变更和取消。
* 每期扣款调用 `/api/v1/order/create`，带 `paymentInfo.userPaymentAccessToken` 和 `paymentInfo.merchantInitiatedMode`。`scheduled` 用于按约定固定周期扣款，`unscheduled` 用于没有固定周期的商户发起扣款。
* 你的账户需要由 Waffo 开通 MIT 能力，开通前不能发起 MIT。需要的话联系你的 Waffo 对接人。

token 怎么拿到、CIT 与 MIT 的区别、失败码，见 [Tokenization 与卡支付 FAQ](https://waffo.com/docs/zh/support/tokenization-faq.md) 和[非卡 Token 与 Token 失败原因](https://waffo.com/docs/zh/support/tokenization-non-card-faq.md)。

## 第一次付款时，怎么顺便保存卡用于以后自动扣款？

如果你已经在用 Waffo 收银台，可以在首单里让 Waffo 把这次用的卡存成 token，不需要你单独做一遍绑卡页面。做法：创建订单时在 `paymentInfo` 里设置 `setupFutureUsage: true`（订单产品类型为 `ONE_TIME_PAYMENT`）。

要点：

* 设置后收银台只展示支持 MIT 的支付方式。
* 不要同时传 `setupFutureUsage` 和 `userPaymentAccessToken`：前者是新建 token，后者是使用已有 token。
* 用户在收银台输入新卡并付款成功后，Waffo 把这张卡存成 token。如果用户选的是已保存的卡，则直接复用，不会重复绑定。
* 对同一个用户请使用稳定的 `userInfo.userId`，之后用 token 扣款时传同一个用户 ID。
* 这条路径**不会**发 `TOKENIZATION_NOTIFICATION`。token 在 `PAYMENT_NOTIFICATION` 的 `result.paymentInfo.userPaymentAccessToken` 里；通知没收到时，调用 `/api/v1/order/inquiry`（传 `paymentRequestId` 或 `acquiringOrderId`），从响应的同一字段读取。

和「商户侧绑卡」的区别：

| 对比 | 收银台首单绑卡 | 商户侧绑卡 |
| - | - | - |
| 入口 | `/api/v1/order/create` + `setupFutureUsage: true` | `/api/v1/tokenization/generate` + 前端 SDK `tokenizationSubmit()` |
| 适用场景 | 用户本来就要付款，顺便存卡 | 不需要同时付款，只想绑卡，或自己设计绑卡界面 |
| 卡信息输入页面 | Waffo 托管的收银台 | 你自己的页面，使用 `@waffo/payment-sdk` |
| 对接工作量 | 较小 | 较大 |
| token 结果怎么拿 | `PAYMENT_NOTIFICATION` 或订单查询 | `TOKENIZATION_NOTIFICATION` |

## 收银台首单绑卡常见问题

| 现象 | 原因与处理 |
| - | - |
| 收银台提示没有可用的支付方式 | `setupFutureUsage: true` 会过滤掉不支持 MIT 的支付方式。确认你的账户有支持 MIT 的卡支付协议；仍然没有可用方式时联系 Waffo 技术支持。 |
| 付款成功了但没收到 token | 先确认收到 `PAYMENT_NOTIFICATION` 并读 `result.paymentInfo.userPaymentAccessToken`；没收到通知就用订单查询取同一字段。不要等 `TOKENIZATION_NOTIFICATION`。 |
| 有 token 但发起不了 MIT | 确认你的账户已由 Waffo 开通 MIT。开通前即使有 token 也不能发起 MIT。 |

## 订阅 API 下的订阅，用户也能自己取消吗？

取决于支付方式。商户侧调用取消接口，所有支付方式都支持。用户在支付方式一侧自己取消（例如 Apple Wallet、Google Pay、PayPay 应用、钱包一侧、Paidy 一侧、PIX 渠道一侧）后，取消会回报给 Waffo，订阅会进入对应的已取消终态，具体状态值见[订阅 FAQ](https://waffo.com/docs/zh/support/subscription-faq.md)。用户也可以在 Waffo 托管的订阅管理页面上取消。

支持预约到某天再取消的做法，见[预约取消与恢复订阅](https://waffo.com/docs/zh/support/subscription-scheduled-cancellation-and-resume-faq.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.