Skip to main content
本页帮你在接入前决定「谁来管订阅」：用 Waffo 的订阅 API 让 Waffo 自动续订，还是自己存 token、自己排期扣款。其中 Waffo 订阅里，续订又分「Waffo 来扣」和「支付方式一侧来扣」两种。接入步骤和字段细节见官网的订阅集成指南与订阅支付方式对比页。

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

按「谁管订阅」分，一共三种做法： ①和②在 Waffo 官网里同属「Waffo 订阅」一种接入方式，对你来说接口是同一套，差别在于续订由谁来执行（见下一问）。③是另一种接入方式。 选择时先问自己三个问题： 具体某个支付方式能不能做订阅、支持到什么程度，以你合同配置和 /api/v1/paymethodconfig/inquiry 的返回为准。

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

两者共用同一套订阅 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 和非卡 Token 与 Token 失败原因。

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

如果你已经在用 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 下的订阅，用户也能自己取消吗？

取决于支付方式。商户侧调用取消接口，所有支付方式都支持。用户在支付方式一侧自己取消（例如 Apple Wallet、Google Pay、PayPay 应用、钱包一侧、Paidy 一侧、PIX 渠道一侧）后，取消会回报给 Waffo，订阅会进入对应的已取消终态，具体状态值见订阅 FAQ。用户也可以在 Waffo 托管的订阅管理页面上取消。 支持预约到某天再取消的做法，见预约取消与恢复订阅。