续费与自动恢复
本页用于处理订阅生效后的续费、失败重试和补偿查询。接入主流程请先阅读 Subscription 集成方案。
处理续费与补扣
- 每个计费周期到期时,PingPong 会按订阅计划自动发起续费。
- 若本次续费失败且开启了
autoRecovery.enabled=true,订阅会进入PAST_DUE,并根据自动重试策略继续尝试补扣。 - 若
autoRecovery.enabled=false,扣款失败后不进入自动重试流程,订阅转为CANCELLED。 - 重试次数和间隔使用平台默认策略(见下方自动重试机制),当前基础能力不支持商户自定义;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 收银台重新完成本期支付:
"action": {
"redirectUrl": "https://sandbox-safepay.pingpongx.com?token=...",
"actionExpiredAt": 1792200000
}redirectUrl:挽回收银台地址。商户可将用户重定向到该地址,或通过站内消息、邮件等渠道引导用户打开,重新支付本期账单。actionExpiredAt:地址有效期(秒级时间戳)。有效期 = 生成时间起 min(72 小时, 自动重试窗口剩余时间):按周期实际约为DAY2 小时、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。完整通知报文示例请见 订阅状态与通知 · 订阅通知报文结构。
收到 SUBSCRIPTION_PAST_DUE 时,建议先把订阅标记为“待补扣”或“宽限期中”,再结合支付结果决定是否继续服务。
查询订阅计划与支付记录
通知延迟、丢失或需要补偿核对时,建议查询时保持订阅层、支付层双视角:
| 查询接口 | 更适合回答什么问题 |
|---|---|
| 查询订阅详情 | 当前订阅是不是 ACTIVE、是不是还在试用期、有没有取消、当前进行到第几期 |
| 查询订阅支付记录 | 第几期扣了多少钱、扣款是否成功、用了什么支付方式、是否有退款 |
