订阅状态与通知
本页用于理解 Subscription 的状态变化和通知结果。接入主流程请先阅读 Subscription 集成方案。
订阅状态流转图
下面这张图建议作为商户内部联调、产品规则设计和客服运营对齐时的共同参考。它描述的是"订阅计划状态"的变化,以及每次状态流转会触发哪个 webhook 事件(边上的标签就是 notifyType):
PENDING -> IN_TRIAL:有试用期,首期授权成功后进入试用。PENDING -> ACTIVE:无试用期,首期支付成功,订阅直接生效。IN_TRIAL -> ACTIVE:试用到期,转正扣款成功。IN_TRIAL -> PAST_DUE:试用到期,转正扣款失败。ACTIVE -> PAST_DUE:到达续费扣款时间,但本次扣款失败。PAST_DUE -> ACTIVE:自动补扣成功,订阅恢复正常。PENDING / ACTIVE / PAST_DUE -> CANCELLED:创建后取消、用户/商户主动取消、到期终止,或自动重试耗尽。
常见订阅状态建议:
PENDING:订阅已创建,但尚未进入正式生效阶段,不建议开通服务。IN_TRIAL:订阅处于试用期,当前服务可用。ACTIVE:订阅正常生效中,用户有权继续使用服务。PAST_DUE:本次续费失败,已进入欠费或自动补扣阶段,是否继续服务由商户自行决策。CANCELLED:订阅已终止,不再继续自动续费。
currentPeriod 的理解方式建议统一如下:
| 值 | 含义 | 建议动作 |
|---|---|---|
0 | 表示试用期 | 正常情况下应同时满足 status=IN_TRIAL 且存在有效的 trial 配置;字段组合冲突时按异常数据处理 |
1 | 当前为首个正式计费周期 | 说明已经完成首期正式生效 |
2 及以上 | 当前为后续续费周期 | 可结合续费记录、状态和权益规则继续履约 |
订阅通知事件类型
推荐按 notifyType(事件类型)+ status(当前状态) 共同处理订阅通知,而不是只看状态变化:
支付结果及由其引起的订阅状态变化,可能分别通过支付通知和订阅通知同步。两类通知应分别验签、分别幂等处理;不要将 webhook 的到达顺序或间隔作为集成依赖。通知缺失、重复或结果不一致时,请通过查询接口做补偿确认。
| notifyType | status | 典型含义 | 商户应做什么 | 是否继续提供服务 |
|---|---|---|---|---|
SUBSCRIPTION_CREATED | PENDING | 订阅创建且待生效(未来 startAt,不立即扣款) | 记录订阅已创建,等待后续扣款结果 | 否 |
SUBSCRIPTION_IN_TRIAL | IN_TRIAL | 进入试用期 | 开通试用权益,记录 currentPeriod=0 | 是 |
SUBSCRIPTION_ACTIVATED | ACTIVE | 首期/转正扣款成功,订阅激活 | 开通正式订阅权益 | 是 |
SUBSCRIPTION_PAST_DUE | PAST_DUE | 续费失败进入宽限 | 按业务规则进入宽限期/降级/提醒补费 | 视业务决定 |
SUBSCRIPTION_RECOVERED | ACTIVE | 宽限期内补扣成功恢复 | 恢复正式服务 | 是 |
SUBSCRIPTION_PLAN_CHANGED | ACTIVE | 套餐变更已生效(改价/改周期) | 更新本地套餐、金额、周期、权益版本;用 previousAttributes 对比变更 diff | 是 |
SUBSCRIPTION_PLAN_CHANGE_SCHEDULED | ACTIVE | 下周期生效的变更已登记 | 记录预约变更内容(pendingUpdate),生效日再处理 | 是 |
SUBSCRIPTION_PLAN_CHANGE_FAILED | ACTIVE | 套餐变更失败(变更整体回滚) | 记录失败原因,提示用户重新变更 | 是 |
SUBSCRIPTION_CANCELLATION_SCHEDULED | ACTIVE | 已标记周期末取消 | 记录 cancelAt(周期末时间),本周期继续履约 | 是 |
SUBSCRIPTION_CANCELLATION_REVOKED | ACTIVE | 周期末取消标记被撤销 | 清除本地"已计划取消"标记 | 是 |
SUBSCRIPTION_CANCELLED | CANCELLED | 订阅已取消 | 关闭自动续费,按取消原因停止或调整服务 | 否 |
当 status=CANCELLED 时,建议进一步按 cancelReason 区分动作:
| cancelReason | 场景 | 商户建议动作 |
|---|---|---|
user_requested | 用户主动取消 | 到取消生效时点停止服务,不再继续自动续费 |
merchant_requested | 商户主动取消 | 按商户侧取消策略处理,必要时同步会员结束时间 |
payment_retry_exhausted | 自动补扣次数已用尽 | 关闭自动续费,决定是否立即停服或结束宽限期 |
plan_ended | 订阅自然到期结束 | 按订阅期满处理,不再继续续费 |
订阅通知报文结构
订阅通知的 bizContent 字段均为 camelCase,时间字段为秒级数字时间戳:
| 字段 | 类型 | 说明 |
|---|---|---|
notifyType | String | 事件类型(见上表) |
merchantSubscriptionId | String | 商户侧订阅计划唯一 ID |
subscriptionId | String | PingPong 订阅单号 |
requestId | String | 触发本次事件的商户请求号 |
status | String | 订阅计划当前状态 |
flatPrice | Object | 当前生效的每期扣款金额和币种 |
period | Object | 订阅周期 {count, unit} |
totalPeriodCount | Integer | 总扣款期数(不含试用期) |
currentPeriod | Integer | 当前周期序号(0=试用期) |
currentPeriodStartAt | Long | 当前计费周期起点,秒级时间戳 |
currentPeriodEndAt | Long | 当前计费周期结束时间,秒级时间戳 |
startAt | Long | 订阅开始时间,秒级时间戳 |
endAt | Long | 订阅结束时间,秒级时间戳 |
updateAt | Long | 本次通知生成时间,秒级时间戳 |
cancelAtPeriodEnd | Boolean | 是否已预约周期末取消 |
previousAttributes | Object | 变更前字段快照(仅变更类事件返回,如 flatPrice、endAt、status),可用于与当前值做 diff |
paymentRecords | Array | 支付记录摘要(续期扣款等资金类事件返回) |
refundRecords | Array | 退款记录(退款类事件返回) |
action | Object | PAST_DUE 挽回动作(仅 SUBSCRIPTION_PAST_DUE 通知且挽回收银台可用时返回):redirectUrl 挽回收银台地址,actionExpiredAt 有效期(秒级时间戳,生成时间起 min(72 小时, 重试窗口剩余时间)) |
discount | Object | 当前生效的折扣配置(配置折扣时返回) |
未来生效创建通知示例(SUBSCRIPTION_CREATED,未来 startAt 不立即扣款):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_SESSION_202607150001",
"notifyType": "SUBSCRIPTION_CREATED",
"status": "PENDING",
"currentPeriod": 0,
"currentPeriodStartAt": 1786692039,
"currentPeriodEndAt": 1789370439,
"startAt": 1786692039,
"endAt": 1789370439,
"updateAt": 1784013639,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"status": "PENDING"
}
}试用期进入通知示例(SUBSCRIPTION_IN_TRIAL):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_SESSION_202607150001",
"notifyType": "SUBSCRIPTION_IN_TRIAL",
"status": "IN_TRIAL",
"currentPeriod": 0,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1784017239,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784013639,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"trial": {
"startAt": 1784013639,
"endAt": 1784017239,
"periodDays": 7
},
"previousAttributes": {
"status": "PENDING"
}
}订阅激活通知示例(SUBSCRIPTION_ACTIVATED,仅展示 bizContent):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_SESSION_202607150001",
"notifyType": "SUBSCRIPTION_ACTIVATED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784013662,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"status": "PENDING"
}
}续费失败进入宽限通知示例(SUBSCRIPTION_PAST_DUE):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_RENEW_202607160001",
"notifyType": "SUBSCRIPTION_PAST_DUE",
"status": "PAST_DUE",
"currentPeriod": 2,
"currentPeriodStartAt": 1785153662,
"currentPeriodEndAt": 1787832062,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1785153662,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"autoRecovery": {
"enabled": true,
"attemptCount": 1,
"maxAttempts": 1,
"status": "ACTIVE"
},
"action": {
"redirectUrl": "https://sandbox-safepay.pingpongx.com?token=...",
"actionExpiredAt": 1792200000
}
}
action为 PAST_DUE 挽回收银台地址,详见 续费与自动恢复 · PAST_DUE 挽回收银台。
宽限期恢复通知示例(SUBSCRIPTION_RECOVERED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_RECOVER_202607170001",
"notifyType": "SUBSCRIPTION_RECOVERED",
"status": "ACTIVE",
"currentPeriod": 2,
"currentPeriodStartAt": 1785153662,
"currentPeriodEndAt": 1787832062,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1785240000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"status": "PAST_DUE"
}
}套餐变更通知示例(SUBSCRIPTION_PLAN_CHANGED,含 previousAttributes diff):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_UPDATE_202607160001",
"notifyType": "SUBSCRIPTION_PLAN_CHANGED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784015000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "15.00",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"flatPrice": {
"amount": "9.99",
"currency": "USD"
}
}
}下周期生效的变更预约通知示例(SUBSCRIPTION_PLAN_CHANGE_SCHEDULED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_UPDATE_202607160001",
"notifyType": "SUBSCRIPTION_PLAN_CHANGE_SCHEDULED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784015000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"pendingUpdate": {
"effectiveMode": "NEXT_CYCLE",
"flatPrice": {
"amount": "15.00",
"currency": "USD"
}
}
}
status保持ACTIVE、顶层flatPrice仍为当前周期价格;预约变更内容在pendingUpdate中,下周期生效后会再收到SUBSCRIPTION_PLAN_CHANGED。
套餐变更失败通知示例(SUBSCRIPTION_PLAN_CHANGE_FAILED,变更整体回滚):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_UPDATE_202607160001",
"notifyType": "SUBSCRIPTION_PLAN_CHANGE_FAILED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784015000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"pendingUpdate": {
"effectiveMode": "IMMEDIATE",
"flatPrice": {
"amount": "15.00",
"currency": "USD"
}
},
"resultCode": "system_internal_gateway_error",
"resultMessage": "Internal gateway error"
}失败的意图保留在
pendingUpdate;订阅价格与状态整体回滚(价仍为 9.99,ACTIVE 不变)。
周期末取消标记通知示例(SUBSCRIPTION_CANCELLATION_SCHEDULED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_CANCEL_202607160001",
"notifyType": "SUBSCRIPTION_CANCELLATION_SCHEDULED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784015000,
"cancelAtPeriodEnd": true,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12
}
status保持ACTIVE,cancelAtPeriodEnd=true表示已标记周期末取消。
撤销周期末取消通知示例(SUBSCRIPTION_CANCELLATION_REVOKED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_UPDATE_202607170001",
"notifyType": "SUBSCRIPTION_CANCELLATION_REVOKED",
"status": "ACTIVE",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1786692039,
"updateAt": 1784100000,
"cancelAtPeriodEnd": false,
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"cancelAtPeriodEnd": true
}
}
cancelAtPeriodEnd从true变回false,表示周期末取消标记已撤销。
订阅取消通知示例(SUBSCRIPTION_CANCELLED):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"subscriptionId": "SUB-2607140720100000000500111522",
"requestId": "REQ_SUB_CANCEL_202607160001",
"notifyType": "SUBSCRIPTION_CANCELLED",
"status": "CANCELLED",
"currentPeriod": 1,
"currentPeriodStartAt": 1784013639,
"currentPeriodEndAt": 1786692039,
"startAt": 1784013639,
"endAt": 1784100000,
"updateAt": 1784100000,
"cancelAtPeriodEnd": false,
"cancelReason": "merchant_requested",
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"previousAttributes": {
"status": "ACTIVE"
}
}
status变为CANCELLED,cancelReason表示取消原因(小写枚举:merchant_requested/user_requested/payment_retry_exhausted/plan_ended)。
支付通知与退款通知
支付通知中的订阅支付结果示例(仅展示 bizContent):
{
"transactionId": "26071400000051156949",
"merchantTransactionId": "SUB_PLAN_202607150001_P1",
"requestId": "074dbbe1-bb21-4bbd-8223-8dd6757d69b1",
"status": "SUCCESS",
"amount": "100.000000",
"currency": "USD",
"invoiceId": "INV-2610161210100000008200011522",
"paymentMethod": {
"type": "VISA"
},
"subscriptionDetail": {
"subscriptionId": "SUB-2607140846100000000900111522",
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"currentPeriod": 1,
"autoRecovery": {
"enabled": true,
"attemptCount": 0,
"maxAttempts": 1,
"status": "ACTIVE"
}
}
}这个示例通常表示:
- 这一期支付已经成功;
- 本次成功的是
currentPeriod=1对应的正式计费周期; invoiceId是关联 Invoice 对账的关键字段(可用它调用票据详情接口);- 可用
merchantTransactionId/transactionId做支付对账; - 可用
subscriptionDetail.subscriptionId继续回挂到订阅主记录。
订阅退款通知示例(仅展示 bizContent):
{
"amount": "4.840000",
"refundTime": "1785293461000",
"remark": "subscription update refund, taskId=517",
"transactionId": "26072900000151333315",
"notifyType": "REFUND",
"merchantTransactionId": "SUB-2607290250100000032300111522_P1",
"currency": "USD",
"merchantRefundId": "SREF-2607290251100000004100151522",
"refundEndingTime": "1785293463485",
"refundId": "26072900010451333317",
"status": "SUCCESS"
}这个示例通常表示:
- 本次退款已经成功;
merchantRefundId/refundId可用于退款维度幂等和对账;merchantTransactionId表示退款关联的原支付商户交易单号;- 退款成功不代表订阅已经取消或套餐已经生效,订阅层状态仍应看订阅通知或查询订阅详情。
查询订阅支付记录响应示例(仅展示 bizContent):
{
"merchantSubscriptionId": "SUB_MER_001",
"subscriptionId": "SUB-1234567890abcdef",
"requestId": "REQ_SUB_PAYMENT_QUERY_001",
"paymentRecords": [
{
"period": 1,
"merchantTransactionId": "SUB-1234567890abcdef_P1",
"transactionId": "PAY-ORDER-1234567890",
"requestId": "SPAY-1234567890",
"amount": "9.99",
"currency": "USD",
"status": "SUCCESS",
"transactionTime": "1785152760000",
"transactionEndingTime": "1785152860000",
"paymentMethod": {
"type": "VISA"
}
}
],
"resultCode": "000000",
"resultMessage": "SUCCESS"
}如果您要回答“这个订阅现在能不能继续给服务”,优先看订阅结果; 如果您要回答“这一期到底有没有扣款成功、扣了多少钱、用了什么支付方式”,优先看支付结果。
注意
时间字段兼容性
API 请求中的 startAt、endAt 按接口定义使用 10 位秒级时间戳字符串。API 响应(查询/变更/取消)返回的 startAt、endAt、cancelAt、transactionTime、transactionEndingTime 等字段为 13 位毫秒级时间戳字符串。订阅通知(webhook)中的 startAt、endAt、updateAt、currentPeriodStartAt、currentPeriodEndAt 为秒级数字时间戳。请按各通道的实际格式解析,并避免使用只能容纳 32 位整数的类型。
