subscription-lifecycle 是一份关于订阅创建之后全流程处理的技能资料,来源为 hainrixz/agente-pagokit。其核心用途是帮助开发者把订阅状态机、催收、按比例计费和取消等环节显式编码,避免因默认分支缺失造成收入损失。
主要能力与要点:
状态机:trialing → active → past_due → canceled,并包含 paused/grace 与重试成功回到 active 的路径。past_due 是关键状态,需明确容忍时长与客户可见行为。
非自愿流失:多数取消源于过期卡、换卡和发卡行拒绝。建议按计划而非立即重试,分散到数天;提前提醒即将过期的卡;使用账户更新器;区分软拒绝(如余额不足,可在发薪日重试)与硬拒绝(如盗卡,不应重试)。
存储凭证框架:首次扣款为客户发起(CIT),后续为商户发起(MIT),需持久化并发送首次扣款的 network transaction id。资料提到 Mastercard 自 2026 年 10 月 23 日起要求在经济相关的 MIT 上携带存储的 Trace ID,Visa 的 Original Transaction ID 已影响批准率;未关联的 MIT 会被拒绝。需在支付方式或订阅上保存 network_transaction_id,并读取 recurring.network_txn_id_required。
按比例计费:三种可选方案——立即按比例计费、下次续费时抵扣、不计比例(续费时生效)。需选定一种并让结账页在点击前说明将收取的费用。
取消:通常采用期末取消,客户保留已付费权益;立即取消并退款是单独选择。取消必须无需联系客服即可完成,并明确告知访问结束时间。
银行授权扣款:SEPA、Bacs、PAD、UPI AutoPay、Pix Automático、PAC 等与卡不同,授权有独立生命周期(created → pending → active,可能需数天激活),每次扣款前需依法提前通知金额和日期;成功并非最终,SEPA 允许 13 个月内提出未授权索赔,Bacs 有直接借记担保;付款人可在银行撤销授权而不通知商户。不应将其建模为存档卡。
生成的订阅集成应包含:完整状态机并显式处理 past_due;带软/硬拒绝分支的催收计划;持久化并发送 network_transaction_id;无需客服即可取消的客户门户或应用内等效功能;支付失败、订阅更新和订阅删除的 webhook 处理器;针对授权扣款的预通知任务和冲正处理器。
反模式:创建订阅后即认为功能完成;立即、反复或永久重试失败扣款;在结账重定向时授予访问权(应在 webhook 或重新获取时授予);把授权扣款轨道当作卡处理;允许在提供商侧已取消的订阅在应用中继续有效。
限制:资料未提供具体代码示例、安装命令、收费信息或平台支持细节,相关事实暂未提供。