订阅解约

主动取消用户订阅。同步接口:接口返回业务成功响应(HTTP 200 + code=0)时 CXH 侧解约动作已全部生效;不存在"已受理但状态未生效"的中间态。

POST /openapi/v1/orders/unsubscribe

请求

字段	必填	说明
`orderNo`	△	CXH 主订单号;与 `externalOrderNo` 二选一
`externalOrderNo`	△	渠道主订单号;与 `orderNo` 二选一
`reason`	—	文本原因(用户主动 / 客诉等),供 CXH 后续核对使用,渠道无需感知

json

{ "orderNo": "SUB...", "reason": "用户主动" }

状态约束

`orderStatus`	可否解约	说明
`INITIALIZING`(A 模式首扣异步处理中)	❌	`420008 SUBSCRIPTION_FIRST_PAYMENT_PENDING`。首扣结果未落定时不可解约(避免"已扣款但订阅已退订"的悖论)。请等首扣 webhook 推送后再发起:`SUCCESS → 主订单转 ACTIVE 后可解约`;`FAIL → 主订单已转 TERMINATED 无需解约`
`ACTIVE`	✅	正常路径;所有未到期期次置 `CANCELED`,已成功 / 已开账期保留
`TERMINATED`(A 模式首扣彻底失败)	✅	仅做状态清理,无后续期
`UNSUBSCRIBED`	🟡 幂等返回	重复解约不报错,幂等返回业务成功响应(`code=0`)+ 当前订单详情,便于网络抖动时安全重试
`COMPLETED`(订阅已自然完结)	❌	`420004 SUBSCRIPTION_ALREADY_COMPLETED`

通用拒绝场景:

场景	错误码
订单不存在或不属于当前渠道	`420001 SUBSCRIPTION_NOT_FOUND`
`orderNo` 与 `externalOrderNo` 均未传	`400001`

接口同步生效内容

CXH 在接口同步返回前完成下列动作,业务成功响应(code=0)返回时全部生效:

主订单状态置为 UNSUBSCRIBED,unsubscribeTime 记录解约时刻
nextPayTime 清空,不再触发后续扣款 / 开账
(A 模式) 已成功 / 已退款的子订单状态保留;WAIT / FAIL_RETRY 的未来期子订单批量置 CANCELED
(A 模式) CXH 调支付通道发起协议解约;通道返回失败仅在 CXH 侧告警,不影响主订单状态
(B 模式) 已 BILLED 期次保留(权益已发,不随渠道侧退款自动回退);未来期不再到期开账 / 不再发权益
推送一次 order.status.changed webhook(详见下文「Webhook 与本接口的关系」)

已发放但未消耗的权益按业务规则处理(详见字段约定 § 权益过期规则)。

模式差异速查

`settlementMode`	已成功 / 已开账期次	后续未到期期次	退款
`CXH_DEDUCT`	不变(`SUCCESS` / `REFUND_*` 保留)	`WAIT` / `FAIL_RETRY` 状态的子订单批量置 `CANCELED`,不再续扣	由 CXH 内部审核处理,渠道侧联系 BD 提交申请
`CHANNEL_COLLECT`	已 `BILLED` 期次保留(权益已发)	不再到期开账 / 不再发权益	CXH 不参与;渠道侧退款由渠道自管,不影响已发权益

响应

返回完整订单详情(同订阅查询响应结构)。关键字段:

json

{
  "orderNo": "SUB...",
  "externalOrderNo": "EXT...",
  "orderStatus": "UNSUBSCRIBED",
  "unsubscribeTime": "2026-04-28 23:00:00",
  "totalPaidAmountCent": 1990,
  "totalRefundAmountCent": 0,
  "nextPayTime": null,
  "redeemUrl": null,
  "paymentRecords": [
    { "paymentOrderNo": "PAY...", "cycleNo": 1, "paymentStatus": "SUCCESS", "amountCent": 1990, "paidAt": "2026-04-15 10:30:00" },
    { "paymentOrderNo": "PAY...", "cycleNo": 2, "paymentStatus": "CANCELED", "amountCent": 1990 }
  ]
}

完整字段定义见订阅查询 § 响应。

Webhook 与本接口的关系

order.status.changed 是 CXH 主订单状态变更的统一通知通道,不限于本接口触发。两套机制独立,渠道侧应同时处理:

解约源	同步返回	webhook 推送
渠道调本接口	✅	✅(给渠道侧异步监听服务用)
用户在 CXH H5 主动解约	✗	✅(渠道唯一感知途径)
客诉 / 合同终止 → CXH 内部运营操作	✗	✅
协议失效等原因 → CXH 自动解约	✗	✅

渠道侧应按 webhook 中的 eventId 幂等去重,避免与同步返回重复处理。

沙箱行为

沙箱解约一律返回业务成功响应(code=0),主订单置 UNSUBSCRIBED,后续期不再扣款。生产环境行为一致(支付机构层失败属内部业务,不影响主订单状态与渠道侧契约)。

订阅解约 ​

POST /openapi/v1/orders/unsubscribe ​

请求 ​

状态约束 ​

接口同步生效内容 ​

模式差异速查 ​

响应 ​

Webhook 与本接口的关系 ​

沙箱行为 ​