我能创建一个在未来某天才开始的订阅吗?
可以。调用/api/v1/subscription/create 时传入 startTime(带时区的 ISO 8601):
- 订阅会立即创建,并在
startTime到达时自动激活——你这边不需要调度器。开始日期之前它已经处于ACTIVE状态,只是尚未消耗任何账单周期,因此请读取startTime(而不是状态)来区分尚未开始的订阅和正在运行的订阅。 - 配置了试用期时,试用从
startTime开始计算;没有试用期时,首次扣款在startTime执行。 startTime必须严格在未来,且最多提前 365 天;不传则保持当前行为(立即开始)。- 激活时 Waffo 推送激活 Webhook;首次扣款失败则进入正常重试流程。
开始日期之前会验证用户的支付方式吗?
会,在创建时通过零元授权验证该支付方式并存储 token 供后续扣款——用户看到的是”仅验证,今天不扣款”的步骤,而不是一次支付。- 如果验证失败,订阅不会创建,API 返回支付方式验证错误——请让用户尝试其他方式。
- 你的合约必须允许零元订单才能走这个流程;否则创建会被拒绝。
- 不会冻结任何资金,因此在开始日期之前取消不需要处理退款。
开始日期之前允许哪些操作?
用户能在已有订阅上更换或添加支付方式吗?
可以,在托管的订阅管理页面上。用户可以添加额外支付方式、设置新的默认方式、调整备用方式顺序或删除某个方式。- 仅支持卡、Apple Pay 和 Google Pay 订阅,且订阅已取消或已过期后不再支持;生效中订阅的默认方式不能删除。
- 订阅详情响应返回
canChangePaymentMethod和已绑定支付方式列表,方便你驱动自己的 UI。 - 新添加的方式用同样的零元授权流程验证;切换默认方式从下一次扣款起生效。
默认支付方式扣款失败会怎样?
如果绑定了备用支付方式,Waffo 会立即按优先级顺序用备用方式重试,不等待正常重试间隔:- 某个备用方式成功时,会给用户发邮件询问是否将其设为新的默认方式(用户确认前,存储的默认方式保持不变)。
- 如果所有备用方式都失败,订单回落到默认方式上配置的重试策略。备用方式的尝试不计入卡组织的滚动重试窗口,也不会触发支付失败邮件——参见订阅重试与支付方式。
我能通过 update 接口上调金额吗?
不能。/api/v1/subscription/update(amount 和 scheduledAmounts 均如此)只接受小于或等于当前值的金额。要多收费,请使用 /api/v1/subscription/change 把用户迁到新套餐。
更新成功后,Waffo 会向订阅者发送价格变更通知邮件(原金额、新金额、生效周期)——前提是你的账户启用了该通知——并向订阅的 notifyUrl 推送 SUBSCRIPTION_UPDATE_NOTIFICATION。update 的响应仍是变更内容的主要记录,请持久化保存;Webhook 只是异步确认同一变更。变更从下一个账单周期起生效;当前周期不受影响。参见订阅金额与按期排程。
Waffo 会给我的终端用户发哪些通知?
Waffo 在关键生命周期节点直接给订阅者发邮件。每种类型可按商户启用或关闭;语言为你设置的订阅cashierLanguage,未设置则由用户币种推导。
精确时间、抑制规则以及如何避免重复发邮件,见发给你客户的订阅邮件。
扣款失败后是怎么重试的?
自动进行,按你合约配置的重试策略;排期会随账单周期调整。其他行为:- 当该周期的尝试次数达到合约上限(该周期的订单关闭;订阅本身保持
ACTIVE),或订阅在开启”取消即关闭重试”设置的情况下被取消时,重试结束。不存在单独的”不可重试拒绝”类别来提前终止重试。 - 卡重试还受卡组织合规规则的上限约束;超出上限的尝试会自动延后。
- 订阅取消的那一刻是否停止待执行的重试,取决于你合约中的一项设置。如果你要求取消后不再有任何尝试,请与集成支持确认该设置。