| 事件名称 | 事件类型 | 触发时机 | 通知数据结构 | 描述 |
|---|---|---|---|---|
| 试用期即将到期通知 | v2.subscription. trial_period_expiring | 试用期剩余时间小于 3 天时，提醒一次 | Subscription | 用户订阅试用期 3 天后到期 。 使用场景： 到期提醒：向用户推送到期提醒。 |
| 首次订阅通知 | v2.subscription.first | 订阅首次生效时 | Subscription | 订阅首次进入试用期或者活跃状态时通知，每个订阅只会发送一次。 使用场景： 订阅成功推送：发送首次订阅成功的消息（如推送、邮件） 权益发放：为用户解锁订阅对应的服务权限（如付费功能、资源额度） |
| 终止订阅通知 | v2.subscription.canceled | 订阅终止时 | Subscription | 订阅实际终止时通知。 使用场景： 终止服务提示：告知用户订阅已终止，明确服务停止时间 权限回收：回收用户付费权益 |
| 订阅价格变更 | v2.subscription.price_changed | 订阅价格变更时 | Subscription | 订阅价格变更时，通知变更具体信息。 |
| 订阅暂停 | v2.subscription.paused | 订阅暂停时通知 | Subscription | 订阅暂停时通知，用于同步订阅状态。 使用场景： 暂停提醒：告知用户订阅已暂停，服务暂时停止 权限调整：暂停用户的订阅权益访问 |
| 订阅重启 | v2.subscription.resumed | 订阅重启时通知 | Subscription | 订阅从暂停状态恢复时通知。 使用场景： 恢复通知：告知用户订阅已重新启用 权益恢复：重新开放用户的订阅权益和服务 |
| 订阅逾期 | v2.subscription.past_due | 订阅逾期时通知 | Subscription | 订阅支付逾期时通知，通常在自动续订扣款失败后进入该状态。 使用场景： 逾期提醒：提醒用户更新支付方式或补缴费用 宽限期管理：进入宽限期，限制部分功能但保留数据 |
| 订阅未支付 | v2.subscription.unpaid | 订阅未支付时通知 | Subscription | 订阅因长期未支付而被标记为未支付状态时通知。 使用场景： 催款通知：最后一次催促用户完成支付 服务限制：暂停或限制用户的订阅服务权限 |
| 撤回取消订阅 | v2.subscription.cancellation_revoked | 撤回取消订阅时通知 | Subscription | 用户撤回之前的取消订阅请求时通知。 使用场景： 状态同步：更新订阅状态为正常，取消之前的终止计划 挽留成功提醒：告知用户订阅将继续，确认服务持续 |
| 请求取消订阅 | v2.subscription.cancellation_requested | 请求取消订阅时通知 | Subscription | 用户请求取消订阅时通知，但订阅尚未实际终止。 使用场景： 挽留机会：触发用户挽留流程，提供优惠或解决方案 状态标记：标记订阅为”待取消”状态，等待周期结束 |
| 订阅固定期限变更 | v2.subscription.fixed_term_updated | 订阅的固定期限被修改时通知 | Subscription | 当订阅的固定期限设置发生变更时通知，包括修改期数、切换是否支持到期转续、转为持续订阅等操作。通知数据中包含 previous_fixed_term_info，记录变更前的固定期限信息。使用场景： 状态同步：同步订阅的固定期限变更，更新本地记录 业务联动：根据固定期限变更调整用户权益或提醒策略 |
| 账单支付成功 | v2.invoice.paid | 一次性商品、首次订阅和订阅续订支付成功时通知 | Invoice | 一次性商品和订阅相关的支付成功时会发送该通知。用于同步账单状态、订阅管理。 使用场景： 账单状态同步：更新账单状态为”已完成”； 订阅管理：续订账单中会包含订阅周期信息，如当前周期数、周期时间等 |
| 账单支付失败 | v2.invoice.payment_failed | 一次性商品、首次订阅和订阅续订支付失败时通知 | Invoice | 一次性商品和订阅相关的支付失败时会发送该通知。不会每次重试支付失败都通知，只在最终支付失败时通知。 使用场景： 失败提醒与引导支付：告知用户支付失败，提供重新支付入口 |
| 账单退款 | v2.invoice.refunded | 当订阅产生的交易单退款成功时通知，用于获取订阅退款信息 | Invoice | 一次性商品和订阅相关的支付发生退款时会发送该事件。用于同步退款状态。 |
| 交易单支付成功 | v2.trades.succeeded | 支付成功时 | Trade | 所有类型的支付成功时会发送该通知，适用于纯金额交易的闭环。 |
| 交易单支付失败 | v2.trades.payment_failed | 支付失败时 | Trade | 所有类型的支付失败时会发送该通知，适用于纯金额交易的闭环。 |
| 退款成功 | v2.refunds.succeeded | 退款成功时 | Refund | 退款实际完成时通知。 使用场景： 退款通知与状态同步：告知用户退款金额，更新退款单状态为”已完成” |
| 退款失败 | v2.refunds.failed | 退款失败时 | Refund | 退款实际失败时通知 使用场景： 状态同步：更新退款单状态为“失败” 重试与人工干预：触发自动重试机制，或通知客服人工排查，及时重新发起退款，避免用户投诉和资金纠纷。 |
| 争议创建通知 | v2.disputes.created | 争议首次创建时 | Dispute | 渠道首次回传争议数据时通知，每个 channel_dispute_id 仅发送一次。使用场景： 争议入账：在商户系统中创建对应争议工单 资金提示：根据 dispute_amount 在结算视图中标记冻结金额 |
| 争议更新通知 | v2.disputes.updated | 争议关键字段变化时 | Dispute | 已存在的争议在状态、原因、金额或截止时间等关键字段发生变化时通知。 使用场景： 状态同步：根据 dispute_status 更新本地争议状态抗辩提醒：根据 dispute_due_time 推送商户证据提交提醒 |