Update 与 Cancel 规则
本页集中说明计划变更和取消订阅的业务规则。接入主流程请先阅读 Subscription 集成方案。
预览并执行计划变更
如果需要升级/降级套餐、修改金额、调整周期或变更商品信息,建议按以下顺序处理:
- 先调用 预览订阅更新 预估本次变更带来的补扣、退款和生效版本。
- 再调用 更新订阅 正式提交变更。
- 根据业务需要设计合适的
effectiveMode、billingAction和prorationMode。
Update 请求必填字段(网关强制校验)
以下五个字段在 Update 请求中必填,缺失会返回 102000 参数错误:
description(订阅计划描述)redirectUrl(变更涉及收银台/3DS 交互时的回跳地址)effectiveMode(生效模式)billingAction(账单处理动作)prorationMode(按比例计费模式)
建议理解以下三类能力:
effectiveMode:决定本次变更是立即生效,还是在下个周期生效。billingAction:决定资金动作发生时间,以及是否保留或重置现有账单锚点。prorationMode:Preview 支持PRORATED、NONE;Update 另外支持CUSTOM(商户自定义金额和方向,需同时传customAmount/customChargeDirection/customCurrency)。- Update 请求中的
cancelAtPeriodEnd不用于发起取消;它用于撤销已通过 Cancel 接口创建的周期末取消预约。当前仅支持传false撤销该预约,不支持通过 Update 传true创建周期末取消。
当前支持的组合如下;未列出的组合暂不支持:
| 变更内容 | effectiveMode | billingAction | 结果 |
|---|---|---|---|
| 只修改金额 | IMMEDIATE | IMMEDIATE_CHARGE_AND_RESET_CYCLE | ✅ 成功,立即按差额补扣/退款 |
| 只修改金额 | IMMEDIATE | IMMEDIATE_CHARGE_AND_KEEP_CYCLE | ⚠️ 沙箱环境偶发 500(修复中,处理方式见下方说明) |
| 只修改金额 | NEXT_CYCLE | NEXT_CYCLE_CHARGE_KEEP_CYCLE | ✅ 成功,返回 chargeResult=NOT_REQUIRED,在下周期执行 |
修改 startAt、扣款日或周期锚点 | IMMEDIATE | IMMEDIATE_CHARGE_AND_RESET_CYCLE | ✅ 成功(锚点重置到当前时间) |
修改 startAt、扣款日或周期锚点 | IMMEDIATE | IMMEDIATE_CHARGE_AND_KEEP_CYCLE | 暂不支持 |
修改 startAt、扣款日或周期锚点 | NEXT_CYCLE | NEXT_CYCLE_CHARGE_KEEP_CYCLE | 暂不支持 |
KEEP_CYCLE 组合返回 500 时的处理建议
沙箱环境中,IMMEDIATE + KEEP_CYCLE 组合的 Update 偶发返回 500 同步错误,该问题正在修复中。如遇 500,不要立即用新的请求重试:建议先调用 查询订阅详情 确认订阅当前状态;确认变更未生效后,可使用原请求(相同 requestId)重试。如需立即扣款变更,也可优先使用 IMMEDIATE + RESET_CYCLE 组合规避。
除了看请求参数,还建议把更新结果拆成“计划是否变更成功”和“这次是否真的发生资金变动”两层理解:
| 处理层 | 重点字段 | 商户应如何理解 |
|---|---|---|
| 订阅层 | resultCode、status、effectivePlanVersion | resultCode=910000 表示变更已受理/执行;status 表示当前订阅状态;effectivePlanVersion 表示变更后的计划版本 |
| 支付层 | chargeResult、chargeAmount、chargeCurrency、chargeDirection | 表示这次升级/降级是否产生补扣或退款,以及该资金动作当前是否已经完成 |
常见 Update 结果可以按下面的矩阵消费:
| 场景 | resultCode | chargeResult | 商户应如何处理 |
|---|---|---|---|
| 需要补扣且补扣成功 | 910000 | SUCCEEDED | 记录计划变更成功,并按支付结果开通或调整权益 |
| 需要补扣但补扣失败 | 910000 | FAILED | 不应直接开通升级权益;建议提示用户重新支付或重新发起变更 |
| 不需要发生资金动作 | 910000 | NOT_REQUIRED | 记录计划变更成功,无需等待支付或退款终态 |
| 需要退款且退款处理中 | 910000 | PENDING | 计划变更已成功,但退款仍需等待退款通知或查询结果确认 |
| 需要退款且退款成功 | 910000 | SUCCEEDED | 记录计划变更成功,并完成退款对账 |
| 需要退款但退款失败 | 910000 | FAILED | 计划变更不因退款失败自动回滚;退款失败需按退款异常单独处理 |
尤其要注意:
preview只是预估结果,不是最终执行结果。update同步响应返回resultCode=910000,只表示计划变更请求已被受理或执行,不代表资金动作一定已经终态。- 如果
chargeResult=PENDING,说明这次更新涉及的补扣或退款还在处理中,商户不应只凭这一条同步响应就完成最终财务确认。 chargeResult只表示本次变更对应的资金动作,不表示订阅变更任务是否仍在处理中。
更新订阅响应示例(仅展示 bizContent):
{
"previewQuoteId": "SUPD-2607150336100000001000141522",
"requestId": "REQ_SUB_UPDATE_202607150001",
"subscriptionId": "SUB-2607140846100000000900111522",
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"status": "ACTIVE",
"effectiveMode": "IMMEDIATE",
"billingAction": "IMMEDIATE_CHARGE_AND_RESET_CYCLE",
"prorationMode": "PRORATED",
"chargeDirection": "CHARGE",
"chargeAmount": "5.32",
"chargeCurrency": "USD",
"chargeResult": "SUCCEEDED",
"effectivePlanVersion": 2,
"resultCode": "910000",
"resultMessage": "success",
"period": {
"unit": "MONTH",
"count": 1
},
"totalPeriodCount": 12,
"flatPrice": {
"amount": "15.00",
"currency": "USD"
},
"notifyUrl": "https://merchant.example.com/notify/subscription",
"startAt": "1792152613237",
"endAt": "1823688613237",
"updatedAt": "1792152608933",
"currentPeriod": 1,
"cancelAtPeriodEnd": false,
"proratedCurrency": "USD",
"action": {
"type": "PAYMENT_REDIRECT_URL",
"paymentRedirectUrl": "https://sandbox-safepay.pingpongx.com?token=...",
"jsSdkUrl": "https://payssr-cdn.pingpongx.com/.../pp-checkout.js?token=..."
}
}这个结果更适合这样消费:
- 订阅层:记录本次变更已被接受以及
effectivePlanVersion,但付费升级涉及权益开通时仍应结合通知和资金终态处理。 - 支付层:因为
chargeResult=SUCCEEDED,本次补扣已完成;如果是PENDING,仍要继续等待支付通知、订阅通知或后续查询结果,再做最终退款/补扣确认。
收银台订阅的补扣跳转支付
通过收银台会话创建的订阅,如果 Update 变更产生的补扣需要买家继续完成支付动作,响应会返回 action 对象:
{
"action": {
"type": "PAYMENT_REDIRECT_URL",
"paymentRedirectUrl": "https://sandbox-safepay.pingpongx.com?token=...",
"jsSdkUrl": "https://payssr-cdn.pingpongx.com/.../pp-checkout.js?token=..."
}
}商户处理建议:
- 当
action.type=PAYMENT_REDIRECT_URL时,将买家重定向到action.paymentRedirectUrl(或使用jsSdkUrl以内嵌方式打开),引导买家在收银台完成补扣支付——与首期支付的收银台打开方式一致。 - 补扣最终结果以支付通知 / 订阅通知为准;收到成功通知前不要提前开通升级后的权益。
action为空对象时表示无需买家继续动作,直接按chargeResult处理即可。
如果本次 Update 可能产生退款,请在 Update 请求中传入 refundNotifyUrl:
{
"previewQuoteId": "SUPD-2607150336100000001000141522",
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"requestId": "REQ_SUB_UPDATE_REFUND_202607150001",
"description": "Downgrade to basic plan",
"redirectUrl": "https://merchant.example.com/subscription/result",
"flatPrice": {
"amount": "5.00",
"currency": "USD"
},
"goods": {
"name": "Membership",
"description": "Monthly membership service",
"sku": "MEMBERSHIP-001",
"unitPrice": "5.00",
"number": "1",
"imgUrl": "https://merchant.example.com/images/membership.png",
"virtualProduct": "Y",
"itemType": "3"
},
"effectiveMode": "IMMEDIATE",
"billingAction": "IMMEDIATE_CHARGE_AND_RESET_CYCLE",
"prorationMode": "PRORATED",
"refundNotifyUrl": "https://merchant.example.com/notify/refund"
}Update 退款建议按以下链路确认:
- Update 同步响应通过
resultCode=910000确认计划变更结果。 - 当
chargeDirection=REFUND且chargeResult=PENDING时,等待退款异步处理。 - 使用 查询订阅详情 获取
refundRecords[].merchantRefundId和原支付订单关联信息。 - 使用 查询订阅支付记录 或退款通知确认金额、币种和最终退款状态。
请注意两个接口均使用 refundNotifyUrl 接收退款结果异步通知。
requestId 兼容性
按接口契约,Update 响应的 requestId 对应本次 Update 请求。如需确认变更是否生效,建议不要仅凭响应中的 requestId 判断,应结合外层业务码、resultCode、previewQuoteId、订阅通知和查询结果综合确认。
Update 与 Cancel 的关系
Cancel 是否能够执行,不只取决于 cancelAtPeriodEnd,还取决于 plan 上是否存在未完成的变更任务。判断时应先确定“是否允许 Cancel”,再根据 cancelAtPeriodEnd 决定立即取消或周期末取消,最后根据 prorationMode 处理退款。
effectiveMode=IMMEDIATE 和 effectiveMode=NEXT_CYCLE 都遵循下面的 Cancel 门禁,不能仅凭 Update 是立即生效或下周期生效,推断 Cancel 一定可以执行。
| 订阅状态 | 是否有处理中的变更任务 | 是否允许 Cancel | 错误码 | 说明 |
|---|---|---|---|---|
ACTIVE | 无 | 允许 | — | 正常取消(立即或周期末) |
ACTIVE | 有(in-flight update task) | 不允许 | 910008 | "subscription has in-flight update task"——等待变更任务完成后再取消 |
非 ACTIVE(如 PENDING) | — | 不允许 | 910005 | "only active subscription supports update"——首期支付未完成时不允许变更/取消 |
Update 与 Cancel 的 prorationMode 关系
以下规则只在通过上方 Cancel 门禁后生效。Update 和 Cancel 的 prorationMode 分别控制各自请求产生的资金调整:Cancel 不会继承或复用 Update 的 prorationMode、金额或方向,而是在取消时点独立计算。
prorationMode | Update 中的含义 | Cancel 立即取消中的含义 |
|---|---|---|
NONE | 不计算未使用周期残值,本次变更无资金调整 | 不退款(Cancel 不传 prorationMode 时按 NONE 处理) |
PRORATED | 按剩余周期比例计算补扣或退款,结果见 chargeDirection / chargeAmount / chargeResult | 按取消时点重新按剩余周期计算退款,不沿用 Update 的 chargeAmount |
CUSTOM | 使用 customAmount + customChargeDirection 自定义本次调整金额和方向 | 使用 customRefundAmount + customCurrency 指定退款金额 |
周期末取消(cancelAtPeriodEnd=true)不产生任何退款动作,prorationMode 不生效。
需要特别注意:
cancelAtPeriodEnd只决定 Cancel 成功后的生效时间,不能绕过 Update 门禁。chargeResult=PENDING只能说明资金动作处理中,不能单独证明变更任务状态;Cancel 门禁应以变更任务状态为准。- 当前门禁失败返回
910005(非 ACTIVE 状态不允许操作)或910008(存在处理中的变更任务),商户不应对这些错误进行高频重试。
取消订阅
取消订阅和退款是两个独立的业务结果:
- Cancel 操作改变的是订阅计划是否继续续费及何时停止;
- 退款针对某一期已经生成的支付子单,不是“退款订阅主单”;
- 单独退款不会自动终止订阅。如果商户还需要停止后续续费,必须同时完成 Cancel;
- 当前 Cancel 接口可通过
prorationMode在立即取消时触发关联退款,但该退款仍然是支付子单层面的资金动作,必须独立确认终态。
因此,Cancel 返回成功只表示取消请求已经执行或预约成功,不表示相关退款已经完成。
商户侧取消订阅
商户可调用 取消订阅 主动终止订阅。
常见处理方式:
- 立即取消:传入
cancelAtPeriodEnd=false,本次请求成功后立即终止订阅;是否退款由prorationMode决定。 - 周期结束取消:传入
cancelAtPeriodEnd=true,表示本周期内继续提供服务,到当前计费周期结束时再自动取消,通常不立即产生退款。
以下取消场景需要特别处理:
| 订阅场景 | Cancel 结果 | 后续扣款 / 重试 |
|---|---|---|
| 试用期内取消 | 默认立即生效 | 不再发起首个正式周期扣款 |
PAST_DUE 欠费或补扣中取消 | 订阅转为 CANCELLED | 停止后续自动重试 |
| 正常生效订阅周期末取消 | 当前周期结束时转为 CANCELLED | 周期结束前继续履约,不生成结束后的新一期扣款 |
| 固定期限自然结束 | 最后一期结束后转为 CANCELLED,cancelReason=plan_ended | 不再生成下一期扣款 |
| cancelAtPeriodEnd | prorationMode | 取消结果 | 退款行为 |
|---|---|---|---|
true | 不传(整个字段省略) | 当前周期结束时取消 | 不立即退款,周期结束前继续履约 |
false | 不传或 NONE | 立即取消 | 不按剩余周期自动折算退款 |
false | PRORATED | 立即取消 | 系统按当前周期剩余价值计算退款 |
false | CUSTOM | 立即取消 | 使用 customRefundAmount 和 customCurrency 发起指定金额退款 |
周期末取消不能传任何退款字段
prorationMode、customRefundAmount、customCurrency、refundNotifyUrl 这四个退款字段仅用于立即取消(cancelAtPeriodEnd=false)。周期末取消(cancelAtPeriodEnd=true)时,这四个字段都应从请求体中省略;若传入会被拒绝(102000)。
周期末取消的正确请求体只含 merchantSubscriptionId、requestId、cancelAtPeriodEnd(可选 subscriptionId),不含任何退款相关字段。
周期末取消的正确请求示例(注意:没有 prorationMode 字段):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"requestId": "REQ_SUB_CANCEL_EOP_202607150001",
"cancelAtPeriodEnd": true
}Cancel 立即取消时,prorationMode 不传默认按 NONE 处理,即不按剩余周期自动折算退款;如果希望系统折算退款,应显式传入 PRORATED。当立即取消可能产生退款时,可传 refundNotifyUrl 接收本次 Cancel 退款异步结果:
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"requestId": "REQ_SUB_CANCEL_NOW_202607150001",
"cancelAtPeriodEnd": false,
"prorationMode": "PRORATED",
"refundNotifyUrl": "https://merchant.example.com/notify/refund"
}CUSTOM 立即取消示例:
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"requestId": "REQ_SUB_CANCEL_CUSTOM_202607150001",
"cancelAtPeriodEnd": false,
"prorationMode": "CUSTOM",
"customRefundAmount": "1.00",
"customCurrency": "USD",
"refundNotifyUrl": "https://merchant.example.com/notify/refund"
}Cancel 退款的最终结果应通过退款通知或 查询订阅支付记录 确认。订阅查询中的 refundRecords 可用于获取 merchantRefundId 和原支付订单关联信息,但当前返回内容不足以单独确认退款金额和终态。退款完成本身也不会再次改变已经确定的订阅取消方式。
商户侧取消建议:
- 先在商户系统记录取消动作和取消方式。
- 调用取消接口后,以 订阅通知 或 查询订阅详情 作为最终确认依据。
- 当
cancelAtPeriodEnd=true时,在周期结束前仍应按当前订阅状态继续履约。 - 如果订阅存在未完成的变更,应先按"Update 与 Cancel 的关系"确认是否满足 Cancel 门槛(
910005/910008)。
买家/支付方式侧取消授权
在支持买家侧取消授权或关闭自动续费的支付方式场景下,买家可能直接在支付方式或钱包侧停止后续扣款授权。
此类情况下,商户应:
- 接收 订阅通知;
- 根据
status和cancelReason更新本地订阅状态; - 当收到
status=CANCELLED且cancelReason=user_requested时,停止后续自动续费,并按商户业务规则处理会员或服务状态。
如果需要区分取消原因,cancelReason 的取值含义和分场景建议动作见 订阅状态与通知 · 订阅通知事件类型。
