> ## 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 向终端用户发送的生命周期通知。

订阅生命周期中的延期开始、支付方式管理和终端用户通知。升级、按期金额和 Webhook 选择见[订阅 FAQ](/docs/zh/support/subscription-faq)。

## 我能创建一个在未来某天才开始的订阅吗？

可以。调用 `/api/v1/subscription/create` 时传入 `startTime`（带时区的 ISO 8601）：

* 订阅会立即创建，并在 `startTime` 到达时自动激活——你这边不需要调度器。开始日期之前它已经处于 `ACTIVE` 状态，只是尚未消耗任何账单周期，因此请读取 `startTime`（而不是状态）来区分尚未开始的订阅和正在运行的订阅。
* 配置了试用期时，试用从 `startTime` 开始计算；没有试用期时，首次扣款在 `startTime` 执行。
* `startTime` 必须严格在未来，且最多提前 365 天；不传则保持当前行为（立即开始）。
* 激活时 Waffo 推送激活 Webhook；首次扣款失败则进入正常重试流程。

## 开始日期之前会验证用户的支付方式吗？

会，在创建时通过**零元授权**验证该支付方式并存储 token 供后续扣款——用户看到的是"仅验证，今天不扣款"的步骤，而不是一次支付。

* 如果验证失败，订阅**不会创建**，API 返回支付方式验证错误——请让用户尝试其他方式。
* 你的合约必须允许零元订单才能走这个流程；否则创建会被拒绝。
* 不会冻结任何资金，因此在开始日期之前取消不需要处理退款。

## 开始日期之前允许哪些操作？

| 操作 | 是否允许 | 行为 |
| - | - | - |
| 取消 | 是 | 状态变为 `MERCHANT_CANCELLED`（从托管页面取消则为 `USER_CANCELLED`）；不会发生任何扣款。 |
| 更新金额（`amount` / `scheduledAmounts`） | 是 | 新值在订阅激活后生效。 |
| 变更套餐（升级 / 降级） | 否 | 订阅未开始时被拒绝。请取消后重新创建。 |
| 查询 | 是 | 返回带 `startTime` 的订阅；尚未消耗任何账单周期。 |

## 用户能在已有订阅上更换或添加支付方式吗？

可以，在托管的订阅管理页面上。用户可以添加额外支付方式、设置新的默认方式、调整备用方式顺序或删除某个方式。

* 仅支持**卡、Apple Pay 和 Google Pay** 订阅，且订阅已取消或已过期后不再支持；生效中订阅的默认方式不能删除。
* 订阅详情响应返回 `canChangePaymentMethod` 和已绑定支付方式列表，方便你驱动自己的 UI。
* 新添加的方式用同样的零元授权流程验证；切换默认方式从下一次扣款起生效。

## 默认支付方式扣款失败会怎样？

如果绑定了备用支付方式，Waffo 会**立即按优先级顺序用备用方式重试**，不等待正常重试间隔：

* 某个备用方式成功时，会给用户发邮件询问是否将其设为新的默认方式（用户确认前，存储的默认方式保持不变）。
* 如果所有备用方式都失败，订单回落到默认方式上配置的重试策略。备用方式的尝试**不**计入卡组织的滚动重试窗口，也不会触发支付失败邮件——参见[订阅重试与支付方式](/docs/zh/support/subscription-retry-and-payment-methods-faq)。

## 我能通过 update 接口上调金额吗？

不能。`/api/v1/subscription/update`（`amount` 和 `scheduledAmounts` 均如此）只接受**小于或等于**当前值的金额。要多收费，请使用 `/api/v1/subscription/change` 把用户迁到新套餐。

更新成功后，Waffo 会向订阅者发送价格变更通知邮件（原金额、新金额、生效周期）——前提是你的账户启用了该通知——并向订阅的 `notifyUrl` 推送 `SUBSCRIPTION_UPDATE_NOTIFICATION`。`update` 的响应仍是变更内容的主要记录，请持久化保存；Webhook 只是异步确认同一变更。变更从下一个账单周期起生效；当前周期不受影响。参见[订阅金额与按期排程](/docs/zh/support/subscription-amount-scheduling-faq)。

## Waffo 会给我的终端用户发哪些通知？

Waffo 在关键生命周期节点直接给订阅者发邮件。每种类型可按商户启用或关闭；语言为你设置的订阅 `cashierLanguage`，未设置则由用户币种推导。

| 通知 | 触发条件 |
| - | - |
| 订阅已激活 | 首期支付成功。 |
| 试用期即将结束提醒 | 在试用期结束前不久发送。 |
| 即将扣款通知 | 在每次扣款前发送，包含试用期。 |
| 支付失败 | 某次计划重试或最后一次尝试失败；包含供用户添加或更新支付方式的链接。首期失败或备用方式的尝试**不**发送。 |
| 取消确认 | 取消完成。 |
| 订阅已变更 | 你通过 update 接口更改了金额。 |

精确时间、抑制规则以及如何避免重复发邮件，见[发给你客户的订阅邮件](/docs/zh/support/subscription-notifications-faq)。

## 扣款失败后是怎么重试的？

自动进行，按你合约配置的重试策略；排期会随账单周期调整。其他行为：

* 当该周期的尝试次数达到合约上限（该周期的订单关闭；订阅本身保持 `ACTIVE`），或订阅在开启"取消即关闭重试"设置的情况下被取消时，重试结束。不存在单独的"不可重试拒绝"类别来提前终止重试。
* 卡重试还受卡组织合规规则的上限约束；超出上限的尝试会自动延后。
* 订阅取消的那一刻是否停止待执行的重试，取决于你合约中的一项设置。如果你要求取消后不再有任何尝试，请与集成支持确认该设置。


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