Monnify 按卡月度失败限额与自动代扣控频
1. 需求目标
Monnify 对合同明确约定的失败扣款按卡统计，每个自然月最多允许失败 22 次。
本需求通过系统自动计数和渐进降频，避免日常代扣任务过早耗尽单卡月度次数：
- 按卡记录当月应计数的明确失败。
- 失败次数越多，自动代扣间隔越长。
- 自动代扣最多消耗当月 18 次失败额度，达到 18 次后暂停该卡当月全部自动代扣。
- 预留剩余 4 次给用户主动处理；达到 22 次时执行通道硬停止。
- 月初由系统自动重置月度次数和控频周期。
全流程由系统自动判断和执行，不设置人工审批、人工重试或受控尝试。
2. 需求范围
2.1 本期包含
- Monnify 卡自动代扣的月度失败计数。
- 按卡渐进降频、18 次自动暂停和 22 次硬停止。
- 自动任务停止后，为用户主动处理预留 4 次失败额度。
- 日常代扣任务的自动判断、执行、跳过、查询和月初重置。
2.2 本期不包含
- 主动还款、H5、虚拟账号和其他支付通道。
- 跨还款方式或跨订单的防重复、敞口占用和互斥判断。
- 人工审批、人工调整次数、人工解锁或人工发起扣款。
- 用户页面提示和前端埋点。
本期只保证自动任务不消耗第 19–22 次额度，不新增用户主动处理入口；用户主动处理沿用现有能力。
3. 统计规则
3.1 统计维度
月度状态按以下维度记录：
Monnify 商户/合同 + 稳定卡指纹 + Africa/Lagos 自然月
- 22 次明确以卡为维度，不以客户、贷款、Token 或内部卡记录为维度。
- 同一张卡解绑重绑、Token 更新或产生多条内部记录时，当月次数不重置。
- 不保存完整卡号；稳定卡指纹不可反向还原。
- 不同 Monnify 商户或合同分别统计。
- 自然月按
Africa/Lagos的每月 1 日 00:00 至月末计算。
3.2 计数条件
计数规则简化为：Monnify 已返回终态失败，且标准化失败原因命中“限频失败原因”配置，则当月次数加 1。
首期“限频失败原因”配置以下 3 项；任一项命中即计数：
Insufficient fundLost cardTransaction Not Permitted to Cardholder
后续新增原因只需扩展配置，不修改计数和阶梯逻辑。
| 结果 | 是否计数 | 系统处理 |
|---|---|---|
| 终态失败，原因命中限频配置 | 是 | 次数加 1，重新计算下一次执行日期 |
| 终态失败，原因未命中限频配置 | 否 | 按现有失败规则结束本次处理 |
| 处理中或结果未知 | 否 | 保留未决状态，只查询原交易 |
| 请求未发送到 Monnify | 否 | 记录调用失败，不作为卡失败次数 |
同一通道参考号最多计数一次；重复通知和重复查询只更新原结果。
3.3 未决状态
- 处理中、超时或未知结果不直接计为失败。
- 系统只查询原通道参考号，不创建新的 Monnify 扣款。
- 查询得到明确计数失败后，自动补记到原请求所属月份并重新计算控频状态。
- 查询得到成功或明确不计数失败后，自动关闭未决状态。
- 未决状态跨月时仍归属原请求月份，不因月初重置而丢失。
4. 渐进降频规则
| 当月已确认计数失败 | 自动代扣频率 | 系统动作 |
|---|---|---|
| 0–11 | 每天最多 1 次 | 满足执行日期时正常进入代扣任务 |
| 12–15 | 每 2 天最多 1 次 | 未到下一次执行日期则自动跳过 |
| 16–17 | 每 3 天最多 1 次 | 未到日期自动跳过，不补跑 |
| 18–21 | 暂停当月自动代扣 | 自动任务不再调用 Monnify，剩余额度留给用户主动处理 |
| 22 及以上 | 当月硬停止 | 调用 Monnify 前强制拦截 |
补充规则：
- 18 次是自动代扣停止线；系统任务最多消耗 18 次失败额度。
- 18 次至 22 次之间的 4 次额度只为用户主动处理预留，不允许自动任务、补跑任务或后台批量任务使用。
- 同一卡同一自然日最多调用 Monnify 一次。
- 间隔从最近一次应计数失败的日期开始计算，到达下一次执行日期当天才可再次进入任务。
- 任务停跑或系统故障造成的漏执行不补跑，也不在恢复后连续扣款。
- 一次扣款成功后，系统结束该卡当前还款任务；月度失败记录保留至月末。
- 卡被停用后，月初只重置失败次数，不自动恢复卡状态。
5. 日历视图参数示例
以下示例用于说明系统如何根据参数在日历中生成可执行日和暂停日，不代表新增人工操作页面。
5.1 示例参数
| 参数 | 示例值 | 含义 |
|---|---|---|
| 统计月份 | 2026-08 | 当前控频自然月 |
| 统计时区 | Africa/Lagos | 日期和月初重置基准 |
| 月初已有失败次数 | 0 | 8 月 1 日从新月份状态开始 |
| 限频失败原因 | Insufficient fund、Lost card、Transaction Not Permitted to Cardholder | 示例中每次调用均因余额不足形成计数失败 |
| 初始频率 | 每天最多 1 次 | 0–11 次对应的频率 |
| 单日最大调用次数 | 1 | 同一卡每日最多一次 |
| 自动暂停阈值 | 18 | 达到后暂停当月自动代扣 |
| 用户预留失败额度 | 4 | 第 19–22 次不再由自动任务消耗 |
| 通道硬上限 | 22 | 系统调用前的兜底限制 |
| 月度重置时间 | 2026-09-01 00:00 | 按 Lagos 时间重置次数和执行周期 |
5.2 2026 年 8 月日历示例
假设每个可执行日均调用一次，且结果均为余额不足。图例：F1 表示形成当月第 1 次限频失败；等待表示未到下一次执行日期。
| 周一 | 周二 | 周三 | 周四 | 周五 | 周六 | 周日 |
|---|---|---|---|---|---|---|
| 1 F1 | 2 F2 | |||||
| 3 F3 | 4 F4 | 5 F5 | 6 F6 | 7 F7 | 8 F8 | 9 F9 |
| 10 F10 | 11 F11 | 12 F12 | 13 等待 | 14 F13 | 15 等待 | 16 F14 |
| 17 等待 | 18 F15 | 19 等待 | 20 F16 | 21 等待 | 22 等待 | 23 F17 |
| 24 等待 | 25 等待 | 26 F18／暂停自动代扣 | 27 用户预留 | 28 用户预留 | 29 用户预留 | 30 用户预留 |
| 31 用户预留 |
系统状态变化：
| 日期 | 执行前次数 | 当日结果 | 执行后次数 | 下一步 |
|---|---|---|---|---|
| 8 月 1 日 | 0 | 余额不足 | 1 | 下一次最早为 8 月 2 日 |
| 8 月 12 日 | 11 | 余额不足 | 12 | 进入每 2 天一次，下一次为 8 月 14 日 |
| 8 月 20 日 | 15 | 余额不足 | 16 | 进入每 3 天一次，下一次为 8 月 23 日 |
| 8 月 26 日 | 17 | 余额不足 | 18 | 停止当月自动代扣，预留剩余 4 次 |
| 9 月 1 日 00:00 | 18 | 月度重置 | 0 | 按新月份规则重新计算 |
按当前阶梯，一张从月初 0 次开始且每次均因余额不足失败的卡，会在 8 月 26 日形成第 18 次自动代扣失败。此后自动任务不再执行，距离 22 次硬上限的 4 次额度留给用户主动处理。
6. 日常任务处理
日常自动代扣任务按以下顺序执行：
- 按稳定卡指纹读取当月控频状态。
- 卡失效、当月暂停或达到 22 次时，记录跳过并结束。
- 存在未决 Monnify 请求时，只查询原交易并结束，不创建新请求。
- 未到
next_eligible_date或当天已经调用过时，记录跳过并结束。 - 满足条件时调用 Monnify 一次。
- 根据权威结果自动更新成功、计数失败、不计数失败或未决状态。
- 计数失败后更新次数、当前阶梯、下一次执行日期和当月状态。
任务跳过时不得创建新的 Monnify 通道参考号，也不得调用通道。所有判断结果和状态变化必须留有系统日志。
7. 月初重置
每月 1 日 00:00 按 Africa/Lagos 自动执行：
- 新建该卡新月份的月度控频状态，失败次数从 0 开始。
- 清除上月因达到 18 次产生的月度暂停。
- 重新计算新月份的首次可执行日期。
- 不恢复已过期、已失效或已被系统停用的卡。
- 不删除上月计数、结果和系统日志。
- 上月未决请求继续查询，并将最终结果回记到原月份。
月初任务重复执行时不得重复创建月度状态或改变已经生成的首次执行日期。
8. 上线方案
- 配置并验证 Monnify 计数失败原因、统计时区和稳定卡指纹。
- 回算当月历史失败和未决请求，避免上线后从 0 开始。
- 影子运行至少 7 个业务日，只记录本应执行、跳过和暂停的结果。
- 校准计数和日期后，启用渐进降频。
- 最后启用 18 次暂停、4 次用户预留和 22 次硬停止。
控频状态服务不可用时，系统暂停新的 Monnify 自动代扣；原交易查询和结果更新继续运行。恢复后不得补跑暂停期间错过的扣款。
9. 验收标准
- 同一张卡解绑重绑、Token 更新或产生多条内部记录时，在相同合同和月份共享一个计数状态。
- 只有真实发送、得到权威终态失败且属于配置原因的请求才计数一次。
- 处理中和未知结果不计数，系统只查询原交易，不创建新请求。
- 各失败区间按配置间隔自动生成
next_eligible_date，未到日期的任务自动跳过。 - 同一卡同一自然日最多调用 Monnify 一次，漏执行不会补跑。
- 自动任务按日历示例最多使用 18 次失败额度；达到 18 次后，该卡当月所有自动任务均跳过。
- 第 19–22 次额度不允许自动任务、补跑任务或后台批量任务使用；用户主动处理产生的计数失败继续累计到同一卡月度状态。
- 达到 22 次时，系统在调用 Monnify 前执行硬停止。
Insufficient fund、Lost card、Transaction Not Permitted to Cardholder命中任一首期限频原因配置时增加次数；其他失败原因不纳入限频计数。- 月初自动创建新月份状态并将次数重置为 0，但不会恢复失效卡。
- 上月未决请求在跨月后仍能查询，并将最终结果记回原月份。
- 日历示例从月初 0 次开始，8 月各执行日、等待日、阶梯切换和 9 月 1 日重置结果与系统计算一致。
- 控频服务异常时新代扣暂停，恢复后不会集中补跑。
- 所有计数、跳过、暂停、重置和查询均由系统自动完成并可追溯。
10. 系统参数
| 参数 | 暂定值 |
|---|---|
| 统计时区 | Africa/Lagos |
| 单卡单日最大调用次数 | 1 次 |
| 0–11 次失败间隔 | 1 天 |
| 12–15 次失败间隔 | 2 天 |
| 16–17 次失败间隔 | 3 天 |
| 自动暂停阈值 | 18 次 |
| 用户预留失败额度 | 4 次；自动任务不得使用第 19–22 次额度 |
| 通道硬上限 | 22 次 |
| 月度重置时间 | 每月 1 日 00:00 |
| 未决查询时限 | 沿用现有 Monnify 原交易查询配置 |
| 限频失败原因 | 首期配置 Insufficient fund、Lost card、Transaction Not Permitted to Cardholder；支持后续配置多个标准失败原因 |
“限频失败原因”作为独立系统参数维护。后续增加原因时只扩展配置，不调整计数逻辑和频率阶梯；新增配置默认只影响生效后确认的失败，不回溯修改历史次数。