--- 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"——首期支付未完成时不允许变更/取消 |