--- title: 订阅状态与通知 permalink: /notes/zh/integrate/subscription/lifecycle/ createTime: '2026/07/15 16:30:00' nosearch: true llm: exclude: true description: '说明 Subscription 订阅状态、notifyType 事件、previousAttributes、currentPeriod、cancelReason,以及订阅通知、支付通知、退款通知的处理方式。' --- 本页用于理解 Subscription 的状态变化和通知结果。接入主流程请先阅读 [Subscription 集成方案](/notes/zh/integrate/subscription/integration/)。 ## 订阅状态流转图 下面这张图建议作为商户内部联调、产品规则设计和客服运营对齐时的共同参考。它描述的是"订阅计划状态"的变化,以及**每次状态流转会触发哪个 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` 不立即扣款): ```json { "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`): ```json { "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`): ```json { "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`): ```json { "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 挽回收银台](/notes/zh/integrate/subscription/renewal-recovery/#past-due-挽回收银台-action)。 宽限期恢复通知示例(`SUBSCRIPTION_RECOVERED`): ```json { "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): ```json { "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`): ```json { "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`,变更整体回滚): ```json { "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`): ```json { "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`): ```json { "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`): ```json { "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`): ```json { "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 对账的关键字段**(可用它调用[票据详情](/notes/zh/subscription/invoice/query/)接口); - 可用 `merchantTransactionId` / `transactionId` 做支付对账; - 可用 `subscriptionDetail.subscriptionId` 继续回挂到订阅主记录。 订阅退款通知示例(仅展示 `bizContent`): ```json { "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`): ```json { "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" } ``` 如果您要回答“这个订阅现在能不能继续给服务”,优先看订阅结果; 如果您要回答“这一期到底有没有扣款成功、扣了多少钱、用了什么支付方式”,优先看支付结果。 ::: warning 注意 - 订阅查询顶层和订阅通知中的 `status` 表示订阅计划状态;支付通知及 `paymentRecords[].status` 表示单笔支付状态。 - `currentPeriod` 位于订阅通知 `bizContent` 顶层,`0` 表示试用期。正常情况下应同时满足 `status=IN_TRIAL` 且存在有效的 `trial` 配置。 - 若您同时接收支付通知和订阅通知,应分别做幂等处理,不要把二者视为同一条通知。 - 若 Update 或 Cancel 触发退款,但退款通知延迟、未达或缺少可关联的退款单号,应使用 [查询订阅支付记录](/notes/zh/subscription/api/paymentsQuery/) 和 [查询订阅详情](/notes/zh/subscription/api/query/) 做补偿确认。 ::: ::: warning 时间字段兼容性 **API 请求**中的 `startAt`、`endAt` 按接口定义使用 10 位秒级时间戳字符串。**API 响应**(查询/变更/取消)返回的 `startAt`、`endAt`、`cancelAt`、`transactionTime`、`transactionEndingTime` 等字段为 13 位毫秒级时间戳字符串。**订阅通知**(webhook)中的 `startAt`、`endAt`、`updateAt`、`currentPeriodStartAt`、`currentPeriodEndAt` 为秒级数字时间戳。请按各通道的实际格式解析,并避免使用只能容纳 32 位整数的类型。 :::