> ## 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 如何重试失败的订阅扣款、何时停止重试以及这对订阅意味着什么、滚动重试窗口如何工作，以及订阅上支付方式的绑定、排序、替换和删除的完整规则。

本页深入讨论订阅扣款失败**之后**会发生什么，以及绑定在订阅上的支付方式。订阅 API 的形态
和应订阅哪些通知，请从
[订阅 FAQ](/docs/zh/support/subscription-faq) 开始；延迟开始和金额更新见
[订阅生命周期](/docs/zh/support/subscription-lifecycle-management)。

## 订阅扣款失败了。Waffo 会自动重试吗？

会。你永远不需要自己触发订阅重试，也不应该为同一周期创建替代订单。

* 该周期的订单进入*需要重试*状态，Waffo 按照从你合约的重试策略推导出的计划重新尝试。
* 每次尝试——包括失败原因和尝试次数——都会通过订阅支付订单通知推送，所以你无需轮询就能
  跟踪整个序列。
* 重试进行期间**订阅本身持续运行**。它的状态不会因为某个周期失败而改变。

## 重试计划是如何决定的？

由你收单协议上的重试策略决定，并且策略是**按账单周期**选择的，而不是一个全局设置。Waffo
把订阅的 `periodType` 和 `periodInterval` 解析为六个桶之一。映射依据周期的**长度**，
桶的边界并不在名称所暗示的位置：

| `periodType` | `periodInterval` | 策略桶 |
| - | - | - |
| `MONTHLY` | 1–3 | `MONTHLY` |
| `MONTHLY` | 4–11 | `QUARTERLY` |
| `MONTHLY` | 12 或更多 | `YEARLY` |
| `WEEKLY` | 1–3 | `WEEKLY` |
| `WEEKLY` | 4 | `MONTHLY` |
| `DAILY` | 1–6 | `DAILY` |
| `DAILY` | 7–29 | `WEEKLY` |
| `DAILY` | 30–119 | `MONTHLY` |
| `DAILY` | 120–364 | `QUARTERLY` |
| `DAILY` | 365 | `YEARLY` |
| 任意 | 未存储间隔 | `DEFAULT` |

让人意外的两个后果：**季度**订阅（`MONTHLY` + `3`）使用 **`MONTHLY`** 桶，而不是
`QUARTERLY`；而**半年**订阅（`MONTHLY` + `6`）才是落入 `QUARTERLY` 的那个。
当你的协议没有为解析出的桶配置策略时，也会使用 `DEFAULT`。

每个桶带有三个参数：**重试间隔**、**间隔单位**（天），以及该周期的**最大尝试次数**。
这些值是商务条款而不是平台常量——请向你的 Waffo 联系人询问你账户上配置的策略，
不要在对账逻辑中硬编码一个假设的计划。

## 在每周期最大次数之上，还有总体重试上限吗？

有。独立于你合约的每周期最大次数，卡重试在账户层面受一个**滚动窗口**限制，
以便 Waffo 在重试频率上保持在卡组织规则之内。

* 窗口是滚动的，不是按日历的：它始终看的是过去一段时间，而不是日历月。
* 当一次尝试会突破窗口时，它不会被判失败——而是**推迟到第一个能容纳它的日期**。
* Waffo 不公布数值上限，因为它跟踪的是卡组织要求而不是 Waffo 的产品决策。把该窗口当作
  重试可能比你合约间隔预测的更晚落地的一个原因。

在**备用**支付方式上进行的尝试被有意排除在此窗口之外（见下文），所以即时的备用尝试永远
不会消耗默认方式的额度。

## Waffo 何时停止重试？订阅会怎样？

满足以下任一条件时重试结束：

| 条件 | 效果 |
| - | - |
| 该周期的尝试次数达到合约最大值 | 该周期的订单被**关闭**。 |
| 订阅已被取消，且你的合约在取消时关闭待处理的重试 | 待重试订单被关闭。 |

重要部分，也是最常见的困惑来源：

当重试耗尽时，**只有该账单周期的订单被关闭。订阅自身的状态保持不变**——它不会进入
已取消或已暂停状态，下一个周期会按计划尝试。

所以一个已关闭的周期订单不是永久撤销客户访问权限的信号。如果你想要催收行为——在 N 个
周期失败后暂停权益、在 M 个周期后取消——你必须在自己这边基于周期级通知实现，
并在你的策略认为该取消时自己调用取消 API。

## 我能从 API 响应判断某次失败是否可重试吗？

没有专门的标志。在当前版本上，订阅失败响应、异步通知和查询响应上都**没有面向商户的
"retryable"字段**。请从以下信息判断你的处境：

* 周期订单的状态（仍在重试 vs. 已关闭），以及
* 该次尝试返回的失败码，以及
* 通知上的尝试次数与你合约的策略对比。

不要基于 `retryPayment` 或 `retryAble` 字段构建逻辑——它们不属于商户契约，也不会为你填充。

## 我在重试待处理时取消了订阅。那些重试会停止吗？

取决于你协议中的一个设置，且范围比"一切都停止"更窄：

* **等待下一次重试的订单**在取消时关闭——但只在你的协议上启用了*取消时关闭重试*设置时。
  它**默认关闭**，所以如果你的要求是取消后绝不再进行任何尝试，请向你的 Waffo 联系人确认。
* **已提交到支付方式的订单**永远不会被取消强制关闭。Waffo 会继续监听它们的结果并报告真实
  结果，因为钱可能已经在流动。预期一个已取消的订阅仍可能产生最后一次成功或失败通知。
* 已处于终态的订单不受影响。

实际后果：调用取消后，让你的 webhook 处理程序仍能接受该订阅的再一次支付结果。

## 一个订阅可以有多个支付方式吗？

可以。订阅携带一个有序列表：一个**默认**方式加上任意数量按优先级排列的**备用**方式。
用户在托管的订阅管理页面上自行管理该列表；订阅详情响应返回 `canChangePaymentMethod`
和已绑定列表，以便你渲染自己的视图。

每个已绑定方式都有自己的状态：

| 状态 | 含义 |
| - | - |
| `IN_PROGRESS` | 已添加，授权尚未完成。不可扣款。 |
| `ACTIVE` | 已验证且可扣款。**唯一可用于扣款的状态。** |
| `EXPIRED` | 已过卡的有效期。由每日检查设置，不是在扣款时。 |
| `SUSPENDED` | 不在收银台提供，也不能作为默认。 |
| `CLOSED` | 终态。包括授权从未完成的方式。 |

## 为什么添加支付方式会创建一笔零金额订单？

因为在 Waffo 对其计费之前，该方式必须被证明可扣款。当用户添加方式时：

1. Waffo 创建一笔专门用于验证该方式的**零金额授权订单**。
2. 响应返回一个**收银台链接**供用户完成授权。该链接被缓存，所以对同一方式重试添加会返回
   同一链接，而不是开启第二次尝试。
3. 该方式被存储为 `IN_PROGRESS`，**不**作为默认。
4. 授权成功后它翻转为 `ACTIVE`。如果之后凭证无法解析，它转为 `CLOSED`——它永远不会
   静默停留在待处理。

验证订单是短时有效的，所以请及时把用户送到链接，而不是存起来以后用。

## 默认支付方式扣款失败时会发生什么？

如果绑定了备用方式，Waffo 会**立即按优先级顺序尝试它们，不等待重试间隔**。这正是备用
方式的全部意义：它把多天的重试周期变成同一时刻的第二次尝试。

* 备用尝试的下一次重试时间被设为*现在*。
* 备用尝试**不**计入滚动窗口，所以它们不消耗默认方式的额度。
* 备用尝试**不会**触发发给用户的重试耗尽邮件。
* 当每个备用方式都尝试过并失败后，默认方式恢复，正常的基于间隔的策略继续。

## 哪些支付方式变更会被阻止？

| 尝试 | 结果 |
| - | - |
| 在非 `ACTIVE` 的订阅上更改方式 | 拒绝。包括已取消和已过期的订阅，也包括其他所有非活跃状态。 |
| 在尚未开始、首次绑定之前的订阅上更改方式 | 允许——这是上述规则的唯一例外。 |
| 删除 `ACTIVE` 订阅的**默认**方式 | 拒绝。先设置另一个默认，再删除。 |
| 删除或设为默认一个非 `ACTIVE` 的方式 | 拒绝。只有 `ACTIVE` 方式是有效目标。 |

## 用户的卡即将过期。Waffo 会提醒他们或刷新卡吗？

两者都不能假设，这一点值得仔细阅读，因为它是最常见的错误预期：

* **Waffo 不会根据发卡行侧的卡更新刷新已存储的卡。** 没有自动的 account-updater 集成。
  当银行换发新卡号或新有效期的卡时，已存储的凭证**不会**静默跟随——请为重新绑定做好计划。
* Waffo 确实会在订阅详情响应上为接近有效期的方式显示一个**即将过期标志**，以便你在自己的
  产品中提示用户。把该标志——而不是一封邮件——当作行动信号。
* 有效期过后，每日检查会把该方式移至 `EXPIRED`，它停止可扣款。
* 钱包类已保存方式不同：当钱包本身通知 Waffo 某凭证已更新或解绑时，该更新会被应用。
  这不适用于普通已存储的卡。

持久的保障是在每个订阅上至少保持一个**备用方式**绑定，并在即将过期标志出现时立即提示用户。

## 购物者的卡在任何扣款之前就在收银台被拒绝了。为什么？

因为有些卡产品不适合周期性计费，你的协议可以携带一个订阅的**被阻止卡子类型**列表。
在收银台期间 Waffo 查询卡的 BIN，如果其子类型在该列表上，卡类方式会从选项中移除。
如果什么都不剩，购物者会看到类似这样的消息：

> Sorry, we do not accept this type of card for subscriptions. Please try a
> different card (e.g., standard Credit or Debit card).

处理时的注意事项：

* 该列表按协议配置。没有固定的平台级黑名单，所以请向你的 Waffo 联系人询问你账户上配置了什么。
* 检查发生在**收银台**，针对购物者实际输入的卡——而不是在你创建订阅时。所以订阅创建可以成功，
  而购物者仍在收银台页面被拒。
* 你的恢复路径与任何拒绝一样：请购物者换一张卡。重试同一张卡不会改变结果。

## 我没有传 `numberOfPeriod`。订阅何时结束？

省略 `numberOfPeriod` 并不意味着"实际上永久"——你的协议携带一个订阅的**最长年数**，
Waffo 据此解析总周期数：

* 省略 `numberOfPeriod` 时，总周期数和结束时间由开始时间加协议的最长时长**推导**得出。
  创建请求被接受；没有任何东西被拒绝。推导值在首个周期成功时写入，所以请从订阅中读回它们，
  而不是自己计算。
* 提供了 `numberOfPeriod` 但长到最后一次扣款会落在该最长时长之外时，创建会被**拒绝**而不是
  截断。同样的检查也适用于 `numberOfTrialPeriod`。你会收到一个没有可用支付方式的错误，
  在这种情况下它意味着"没有协议能承载这么长的订阅"，而不是"这张卡不受支持"。

卡有效期**不是**这两种计算的输入。明年过期的卡不会缩短订阅；它只意味着该方式会移至
`EXPIRED`，你需要绑定一个新的。


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