订阅通知
订阅异步通知
application/json异步通知公共参数
bizContent
periodObject必填订阅周期信息。countInteger必填单个正式计费周期包含的单位数量,必须大于等于 1。例如,unit 为MONTH、count 为1表示每月计费一次;此字段不是订阅总期数。unitString必填订阅周期单位类型,有效值包括:YEAR:表示订阅周期以年为单位。MONTH:表示订阅周期以月为单位。WEEK:表示订阅周期以周为单位。DAY:表示订阅周期以天为单位。
flatPriceObject可选当前生效的每期扣款金额和币种;变更类事件可与previousAttributes.flatPrice对比获得改价 diff。amountString(12)必填订阅计划每个正式计费周期的实际扣款金额。currencyString(3)必填订阅计划正式计费周期的扣款币种,使用三位字母的 ISO 4217 币种代码。
discountObject可选当前生效的订阅折扣配置;未配置折扣时不返回。typeString(32)必填折扣类型。有效值:fixedAmount:固定金额折扣。percentage:百分比折扣。
amountOffString(12)按条件选固定金额减免。仅当 type 为fixedAmount时传入;与 percentOff 互斥。percentOffString(12)按条件选百分比减免值。仅当 type 为percentage时传入;与 amountOff 互斥。durationCountString(12)必填折扣持续的正式计费周期数,不包含试用期。
paymentRecordsArray可选订阅计划下已产生的支付记录摘要,续期扣款等资金类事件时返回。periodInteger必填所属订阅期次。merchantTransactionIdString(64)必填该期对应的商户交易单号。
refundRecordsArray可选订阅计划下涉及的退款记录,退款类事件时返回。merchantRefundIdString(64)必填退款订单号。originalMerchantTransactionIdString(64)必填退款单对应的原支付商户交易单号。
actionObject按条件选PAST_DUE 挽回动作。仅SUBSCRIPTION_PAST_DUE通知且挽回收银台可用时返回;自动重试窗口耗尽后不再生成。商户可引导用户访问redirectUrl重新完成本期支付,链接在actionExpiredAt前有效。redirectUrlString(512)必填挽回收银台地址,用户可在有效期内访问该地址重新完成本期支付。actionExpiredAtLong必填挽回地址有效期,秒级时间戳数字。有效期 = 生成时间起 min(72 小时, 自动重试窗口剩余时间)。
merchantSubscriptionIdString(64)必填商户定义的订阅计划唯一 ID。subscriptionIdString(64)必填PingPong 订阅单号。requestIdString(64)必填触发本次事件的商户请求唯一编号。注意:走 Preview→quote 路径的更新,该字段会归因到 Preview 请求号(已知问题)。notifyTypeString(64)必填订阅事件类型。有效值包括:SUBSCRIPTION_CREATED订阅创建且待生效(未来 startAt,不立即扣款)。SUBSCRIPTION_IN_TRIAL进入试用期。SUBSCRIPTION_ACTIVATED首期/转正扣款成功,订阅激活。SUBSCRIPTION_PAST_DUE续费失败进入宽限。SUBSCRIPTION_RECOVERED宽限期内补扣成功恢复。SUBSCRIPTION_PLAN_CHANGED订阅计划变更已生效(改价/改周期等)。SUBSCRIPTION_PLAN_CHANGE_SCHEDULED已预约下周期生效的计划变更(NEXT_CYCLE)。SUBSCRIPTION_PLAN_CHANGE_FAILED套餐变更失败(变更整体回滚,不产生资金动作)。SUBSCRIPTION_CANCELLATION_SCHEDULED已预约周期末取消。SUBSCRIPTION_CANCELLATION_REVOKED周期末取消预约已撤销。SUBSCRIPTION_CANCELLED订阅已取消。
statusString(32)必填订阅计划当前状态,商户根据该状态决策是否继续给用户提供服务。PENDING订阅已创建,但尚未进入正式生效阶段。IN_TRIAL订阅处于试用期内,当前服务可用,但尚未完成首次正式收费。ACTIVE订阅当前正常生效中,用户有权使用服务。PAST_DUE订阅已到应扣款时间,但本次扣款失败,进入欠费/补扣阶段。CANCELLED订阅已终止,不再继续自动续费。
previousAttributesObject可选变更前字段快照,仅包含本次实际发生变化的字段(如flatPrice、endAt、status),可用于与当前值做 diff。创建类事件不返回。currentPeriodInteger必填当前所在周期,0、1、2、3...,其中0代表试用期。currentPeriodStartAtLong可选当前计费周期的真实起点,秒级时间戳数字。KEEP_CYCLE 变更后锚点周期保持不变,以此字段为准(查询接口的 startAt 可能被刷新为变更时间,仅作展示)。currentPeriodEndAtLong可选当前计费周期的结束时间,秒级时间戳数字。cancelAtPeriodEndBoolean可选是否已预约在周期末取消。totalPeriodCountInteger可选订阅计划包含的正式扣款周期总数,不包含试用期。startAtLong可选订阅开始时间,秒级时间戳数字。endAtLong可选订阅结束时间,秒级时间戳数字。updateAtLong可选本次订阅状态或计划变更的通知时间,秒级时间戳数字。
异步通知报文示例(SUBSCRIPTION_PLAN_CHANGED)
{
"clientId": "2018092714313010016",
"bizContent": {
"merchantSubscriptionId": "SUB_M_202606110001",
"subscriptionId": "SUB-4834bc25d7de4364bee0e24b66d5e5d6",
"requestId": "UPMVAXDTRO5501",
"notifyType": "SUBSCRIPTION_PLAN_CHANGED",
"status": "ACTIVE",
"flatPrice": {
"amount": "18.000000",
"currency": "USD"
},
"discount": {
"type": "percentage",
"percentOff": "10",
"durationCount": "3"
},
"period": {
"count": 1,
"unit": "MONTH"
},
"totalPeriodCount": 12,
"currentPeriod": 1,
"currentPeriodStartAt": 1792152638,
"currentPeriodEndAt": 1794831038,
"startAt": 1792152638,
"endAt": 1823688638,
"updateAt": 1792152638,
"cancelAtPeriodEnd": false,
"previousAttributes": {
"flatPrice": {
"amount": "10.000000",
"currency": "USD"
},
"endAt": 1823688626
}
},
"sign": "2984C6FEF784BE9841DCC70E8F511030",
"accId": "2018092714313010016745",
"signType": "MD5"
}