--- title: 续费与自动恢复 permalink: /notes/zh/integrate/subscription/renewal-recovery/ createTime: '2026/07/15 16:30:00' nosearch: true llm: exclude: true description: '说明 Subscription 自动续费、续费失败、PAST_DUE、自动重试、补扣和支付记录查询建议。' --- 本页用于处理订阅生效后的续费、失败重试和补偿查询。接入主流程请先阅读 [Subscription 集成方案](/notes/zh/integrate/subscription/integration/)。 ## 处理续费与补扣 - 每个计费周期到期时,PingPong 会按订阅计划自动发起续费。 - 若本次续费失败且开启了 `autoRecovery.enabled=true`,订阅会进入 `PAST_DUE`,并根据自动重试策略继续尝试补扣。 - 若 `autoRecovery.enabled=false`,扣款失败后不进入自动重试流程,订阅转为 `CANCELLED`。 - 重试次数和间隔使用平台默认策略(见下方[自动重试机制](#自动重试机制与-past-due-挽回动作)),当前基础能力不支持商户自定义;Hard decline、风控拒绝等不可重试结果不会进入自动重试。 - 自动重试耗尽后,订阅转为 `CANCELLED`,订阅通知中 `cancelReason=payment_retry_exhausted`。 - 商户应根据 `status`、`currentPeriod` 和自身服务策略,决定是否继续向用户提供服务、限期补扣或降级。 ## 自动重试机制与 PAST_DUE 挽回动作 默认自动重试策略按订阅周期取间隔与次数: | 周期单位 | 重试间隔 | 默认最大重试次数 | |:---|:---:|:---:| | `DAY` | 2 小时 | 1 | | `WEEK` | 24 小时 | 7 | | `MONTH` | 48 小时 | 7 | | `YEAR` | 72 小时 | 7 | ### PAST_DUE 挽回收银台(action) 续费扣款失败、订阅进入 `PAST_DUE` 时,订阅通知(`SUBSCRIPTION_PAST_DUE`)会携带 `action` 对象,用于引导用户回到 PingPong 收银台重新完成本期支付: ```json "action": { "redirectUrl": "https://sandbox-safepay.pingpongx.com?token=...", "actionExpiredAt": 1792200000 } ``` - `redirectUrl`:挽回收银台地址。商户可将用户重定向到该地址,或通过站内消息、邮件等渠道引导用户打开,重新支付本期账单。 - `actionExpiredAt`:地址有效期(秒级时间戳)。有效期 = 生成时间起 **min(72 小时, 自动重试窗口剩余时间)**:按周期实际约为 `DAY` 2 小时、`WEEK` / `MONTH` / `YEAR` 最长 72 小时。 - 自动重试窗口耗尽后不再生成 `action`(通知不携带该字段),历史链接也随之失效,订阅将按重试耗尽流程处理(`cancelReason=payment_retry_exhausted`)。 建议商户在收到 `SUBSCRIPTION_PAST_DUE` 通知后尽快把 `action.redirectUrl` 触达用户——`DAY` 周期订阅的有效期只有约 2 小时。 建议把续费场景拆成下面两步判断: | 先看什么 | 关注字段 | 典型含义 | 建议动作 | |:---|:---|:---|:---| | 订阅层 | `status=ACTIVE` | 当前订阅处于正常履约状态 | 继续提供服务 | | 订阅层 | `status=PAST_DUE` | 本期应扣款失败,已进入补扣或宽限期 | 按您的规则继续服务、降级服务或提醒补费 | | 订阅层 | `status=CANCELLED` + `cancelReason=payment_retry_exhausted` | 自动重试结束,订阅终止 | 停止续费和服务 | | 支付层 | 当期支付 `status=SUCCESS` | 这一期已实际扣款成功 | 正常入账、对账 | | 支付层 | 当期支付失败或没有成功记录 | 这一期钱还没收上来 | 结合订阅状态进入催付、宽限或停服流程 | 建议至少定义以下续费失败策略之一: - 宽限期继续服务:在 `PAST_DUE` 期间暂时继续服务,并提醒用户补费。 - 宽限期降级服务:保留账号,但关闭高级权益。 - 立即停服:续费失败后立刻停止订阅服务。 续费失败进入宽限期时,订阅通知会推送 `notifyType=SUBSCRIPTION_PAST_DUE`(`status=PAST_DUE`),补扣成功后推送 `SUBSCRIPTION_RECOVERED`。完整通知报文示例请见 [订阅状态与通知 · 订阅通知报文结构](/notes/zh/integrate/subscription/lifecycle/#订阅通知报文结构)。 收到 `SUBSCRIPTION_PAST_DUE` 时,建议先把订阅标记为“待补扣”或“宽限期中”,再结合支付结果决定是否继续服务。 ## 查询订阅计划与支付记录 通知延迟、丢失或需要补偿核对时,建议查询时保持订阅层、支付层双视角: | 查询接口 | 更适合回答什么问题 | |:---|:---| | [查询订阅详情](/notes/zh/subscription/api/query/) | 当前订阅是不是 `ACTIVE`、是不是还在试用期、有没有取消、当前进行到第几期 | | [查询订阅支付记录](/notes/zh/subscription/api/paymentsQuery/) | 第几期扣了多少钱、扣款是否成功、用了什么支付方式、是否有退款 |