Skip to main content
本页解答商户关于 Waffo 订阅最常问的问题。字段级契约见 订阅 API 规范。

​
怎么给用户升级或降级套餐？

调用 /api/v1/subscription/change。变更请求会基于原订阅创建一个新订阅，原订阅的剩余金额会结转到新订阅上——您不需要手动取消再重新创建。
  • 通过 /api/v1/subscription/change/inquiry 跟踪结果。
  • 变更完成时，Waffo 也会推送 SUBSCRIPTION_CHANGE_NOTIFICATION。

​
change、update 和 manage 有什么区别？

金额更新会按您的合同限额校验。

​
不同周期能收不同的金额吗？

可以。两种机制组合起来可以覆盖分级定价和首期优惠：
  • 试用期——创建订阅时设置 trialPeriodAmount 和 numberOfTrialPeriod。通过 trialPeriodType 和 trialPeriodInterval 支持自定义试用粒度。
  • 计划金额——为特定的正式周期配置按期金额（例如首期折扣），可在创建时配置，也可之后通过 /api/v1/subscription/update 配置。
如果某个周期没有计划金额，则使用订阅的基础 amount。

​
扣款失败了，接下来会怎样？

扣款失败会按订阅的重试策略自动重试——您不需要自己触发重试。
  • 每一次支付尝试，包括失败原因、时间戳和重试详情，都会通过订阅支付订单通知推送。
  • 如果您只关心每个计费周期的最终结果，请改为监听 SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION——它每个周期触发一次，携带最终结果，跳过中间的重试事件。
具体的重试计划和上限取决于您合同中配置的重试策略。如需了解您账户的确切策略，请联系集成支持。

​
我应该监听哪些订阅通知？

对任何通知，处理完成后请返回 success。如果 Waffo 收到 failed 或 unknown，Waffo 会按分布在接下来一天内的退避计划重试通知；计划详情见Webhook 通知重试。

​
用户怎么取消订阅？

两条路径：
  • 商户发起——调用 /api/v1/subscription/cancel。
  • 用户发起——把用户重定向到通过 /api/v1/subscription/manage 获得的托管管理页面，用户可在那里查看详情并取消。
  • 钱包侧——如果用户在钱包 App 内撤销了支付授权，钱包会通知 Waffo。如果被撤销的支付方式是订阅上唯一的一个，订阅会自动取消；如果有备用支付方式，则备用方式成为默认。这会通过订阅状态通知告知您，因此请以Webhook 通知——而不是您自己的记录——作为订阅是否仍然有效的事实来源。
订阅一旦进入已取消状态，就不会再开启新的计费周期。已挂起的重试是否会被立即丢弃取决于您合同中的一项设置——如果这对您重要，请向集成支持确认。

​
Waffo 支持按日计费或跨币种订阅吗？

两者都支持：
  • DAILY 是受支持的 periodType，与其他计费周期并列。
  • 通过 userCurrency 字段支持跨币种订阅——用户以其本地币种支付。
各支付方式的能力和限制列在订阅 API 规范的附录中。

​
subscriptionManagementUrl 应该传什么？

subscriptionManagementUrl 在创建订阅时的文档定义为必填，您应始终传入。请注意，服务端目前不会拒绝省略该字段的请求——省略不会以校验错误的形式暴露，而是会在之后以发送到您页面的客户邮件中缺少链接的形式暴露。请将其指向一个用户可以在桌面浏览器中打开的页面。App deeplink 在这里是很差的选择：在 PC 上打开的用户可能根本无法访问该页面。您有三个选项：
  • 自建带鉴权的订阅管理页面并传入其 URL。
  • 用您自己的页面包裹 Waffo 从 /api/v1/subscription/manage 返回的托管页面，并传入该页面。
  • 直接使用 Waffo 的托管管理页面。
该页面是一个功能入口，不是支付流程中的一步。它不会在实时交易中展示；您应在订阅支付成功后展示它——在用户的账户区、订单确认页，或您站点上任何合适的位置。

​
我收到了订阅通知，但马上查询却显示订阅不是 ACTIVE

订阅状态是最终一致的。通知到达时，内部状态更新可能仍在落地，因此紧接着发起的查询可能返回尚未 ACTIVE 的状态。这是读取时机的问题，不是订阅失败。 请这样处理：
  • 不要把第一次查询结果当作最终结果。稍作等待后重新查询。
  • 优先以订阅状态通知作为状态变化的触发器，用查询来确认而不是决策。

​
试用期金额可以和常规金额一样吗？

不可以。创建时 trialPeriodAmount 必须严格小于 amount；相等的值会被拒绝，返回参数错误，报错信息为 trial period amount should be less than subscription amount。零是有效的试用金额（免费试用），因此可接受范围为 0 ≤ trialPeriodAmount < amount。 如果试用的目的是调整计费日历而不改变价格，请完全不要配置试用——用 startTime 推迟首次扣款，或用 scheduledAmounts 为特定早期周期定价。