--- title: Update 与 Cancel 规则 permalink: /notes/zh/integrate/subscription/update-cancel/ createTime: '2026/07/15 16:30:00' nosearch: true llm: exclude: true description: '说明 Subscription 计划变更、Update 生效模式、资金调整、Cancel 门禁、取消生效方式和退款处理规则。' --- 本页集中说明计划变更和取消订阅的业务规则。接入主流程请先阅读 [Subscription 集成方案](/notes/zh/integrate/subscription/integration/)。 ## 预览并执行计划变更 如果需要升级/降级套餐、修改金额、调整周期或变更商品信息,建议按以下顺序处理: 1. 先调用 [预览订阅更新](/notes/zh/subscription/api/preview/) 预估本次变更带来的补扣、退款和生效版本。 2. 再调用 [更新订阅](/notes/zh/subscription/api/update/) 正式提交变更。 3. 根据业务需要设计合适的 `effectiveMode`、`billingAction` 和 `prorationMode`。 ::: warning 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` | 暂不支持 | ::: warning KEEP_CYCLE 组合返回 500 时的处理建议 沙箱环境中,`IMMEDIATE + KEEP_CYCLE` 组合的 Update 偶发返回 `500` 同步错误,该问题正在修复中。如遇 `500`,**不要立即用新的请求重试**:建议先调用 [查询订阅详情](/notes/zh/subscription/api/query/) 确认订阅当前状态;确认变更未生效后,可使用原请求(相同 `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`): ```json { "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` 对象: ```json { "action": { "type": "PAYMENT_REDIRECT_URL", "paymentRedirectUrl": "https://sandbox-safepay.pingpongx.com?token=...", "jsSdkUrl": "https://payssr-cdn.pingpongx.com/.../pp-checkout.js?token=..." } } ``` 商户处理建议: 1. 当 `action.type=PAYMENT_REDIRECT_URL` 时,将买家重定向到 `action.paymentRedirectUrl`(或使用 `jsSdkUrl` 以内嵌方式打开),引导买家在收银台完成补扣支付——与首期支付的收银台打开方式一致。 2. 补扣最终结果以支付通知 / 订阅通知为准;收到成功通知前不要提前开通升级后的权益。 3. `action` 为空对象时表示无需买家继续动作,直接按 `chargeResult` 处理即可。 如果本次 Update 可能产生退款,请在 Update 请求中传入 `refundNotifyUrl`: ```json { "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 退款建议按以下链路确认: 1. Update 同步响应通过 `resultCode=910000` 确认计划变更结果。 2. 当 `chargeDirection=REFUND` 且 `chargeResult=PENDING` 时,等待退款异步处理。 3. 使用 [查询订阅详情](/notes/zh/subscription/api/query/) 获取 `refundRecords[].merchantRefundId` 和原支付订单关联信息。 4. 使用 [查询订阅支付记录](/notes/zh/subscription/api/paymentsQuery/) 或退款通知确认金额、币种和最终退款状态。 请注意两个接口均使用 `refundNotifyUrl` 接收退款结果异步通知。 ::: warning 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 返回成功只表示取消请求已经执行或预约成功,不表示相关退款已经完成。 ### 商户侧取消订阅 商户可调用 [取消订阅](/notes/zh/subscription/api/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` 发起指定金额退款 | ::: warning 周期末取消不能传任何退款字段 `prorationMode`、`customRefundAmount`、`customCurrency`、`refundNotifyUrl` 这四个退款字段仅用于立即取消(`cancelAtPeriodEnd=false`)。周期末取消(`cancelAtPeriodEnd=true`)时,这四个字段**都应从请求体中省略**;若传入会被拒绝(`102000`)。 周期末取消的正确请求体只含 `merchantSubscriptionId`、`requestId`、`cancelAtPeriodEnd`(可选 `subscriptionId`),不含任何退款相关字段。 ::: 周期末取消的正确请求示例(注意:没有 `prorationMode` 字段): ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "requestId": "REQ_SUB_CANCEL_EOP_202607150001", "cancelAtPeriodEnd": true } ``` Cancel 立即取消时,`prorationMode` 不传默认按 `NONE` 处理,即不按剩余周期自动折算退款;如果希望系统折算退款,应显式传入 `PRORATED`。当立即取消可能产生退款时,可传 `refundNotifyUrl` 接收本次 Cancel 退款异步结果: ```json { "merchantSubscriptionId": "SUB_PLAN_202607150001", "requestId": "REQ_SUB_CANCEL_NOW_202607150001", "cancelAtPeriodEnd": false, "prorationMode": "PRORATED", "refundNotifyUrl": "https://merchant.example.com/notify/refund" } ``` CUSTOM 立即取消示例: ```json { "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 退款的最终结果应通过退款通知或 [查询订阅支付记录](/notes/zh/subscription/api/paymentsQuery/) 确认。订阅查询中的 `refundRecords` 可用于获取 `merchantRefundId` 和原支付订单关联信息,但当前返回内容不足以单独确认退款金额和终态。退款完成本身也不会再次改变已经确定的订阅取消方式。 商户侧取消建议: 1. 先在商户系统记录取消动作和取消方式。 2. 调用取消接口后,以 [订阅通知](/notes/zh/notify/subscription/notify/) 或 [查询订阅详情](/notes/zh/subscription/api/query/) 作为最终确认依据。 3. 当 `cancelAtPeriodEnd=true` 时,在周期结束前仍应按当前订阅状态继续履约。 4. 如果订阅存在未完成的变更,应先按"Update 与 Cancel 的关系"确认是否满足 Cancel 门槛(`910005`/`910008`)。 ### 买家/支付方式侧取消授权 在支持买家侧取消授权或关闭自动续费的支付方式场景下,买家可能直接在支付方式或钱包侧停止后续扣款授权。 此类情况下,商户应: 1. 接收 [订阅通知](/notes/zh/notify/subscription/notify/); 2. 根据 `status` 和 `cancelReason` 更新本地订阅状态; 3. 当收到 `status=CANCELLED` 且 `cancelReason=user_requested` 时,停止后续自动续费,并按商户业务规则处理会员或服务状态。 如果需要区分取消原因,`cancelReason` 的取值含义和分场景建议动作见 [订阅状态与通知 · 订阅通知事件类型](/notes/zh/integrate/subscription/lifecycle/#订阅通知事件类型)。