取消订阅接口 - 前端对接文档

接口信息

项目	值
URL	`/cancelSubscription`
方法	`POST`
Content-Type	`application/json`

业务流程

接口采用两阶段模式：

1. 用户点击取消 → 调 CREATE 提交取消 → 拿到 10201（处理中）
2. 前端轮询     → 调 SELECT 查询状态 → 直到拿到 10200（成功）或 10203（失败）

请求参数

字段	类型	必填	说明
`account`	String	是	用户账号
`loginId`	String	是	登录态 ID
`subscriptionId`	String	是	PayPal 订阅 ID
`cancelOperation`	Integer	否	`0`=提交取消（默认值），`1`=查询状态。不传时按 `0` 处理

请求示例

第一步：提交取消（cancelOperation 可不传，默认按 0 处理）

{
  "account": "user123",
  "loginId": "xxx",
  "subscriptionId": "I-BW1234567890"
}

或显式传 cancelOperation=0：

{
  "account": "user123",
  "loginId": "xxx",
  "subscriptionId": "I-BW1234567890",
  "cancelOperation": 0
}

第二步：查询状态（必须显式传 cancelOperation=1）

{
  "account": "user123",
  "loginId": "xxx",
  "subscriptionId": "I-BW1234567890",
  "cancelOperation": 1
}

响应结构

{
  "code": 200,
  "msg": "提示消息",
  "data": {
    "cancelOperation": 0,
    "paypalStatus": "204",
    "orderCancelStatus": "PENDING",
    "bizCode": 10201
  }
}

字段	类型	说明
`code`	int	HTTP 码：`200`=成功，`500`=失败
`msg`	String	提示消息（可直接展示给用户）
`data`	Object	业务数据，见下表
`data.cancelOperation`	Integer	回显操作类型
`data.paypalStatus`	String	PayPal 端状态（可能为 null）
`data.orderCancelStatus`	String	本地订单状态
`data.bizCode`	Integer	核心字段，前端据此判断终态

bizCode 判断逻辑（核心）

bizCode	含义	前端处理
`10201`	处理中	继续轮询 SELECT
`10200`	取消成功	停止轮询，展示成功
`10203`	取消失败	停止轮询，展示失败

判断伪代码：

if (bizCode === 10200) {
  // 取消成功，结束
} else if (bizCode === 10203) {
  // 取消失败，展示 msg
} else if (bizCode === 10201) {
  // 处理中，继续轮询
} else {
  // 未知状态，按失败处理或上报
}

orderCancelStatus 取值（辅助参考）

前端主要看 bizCode，orderCancelStatus 仅作辅助展示或调试用：

值	含义
`PENDING`	CREATE 已提交，等待回调
`Y`	本地仍为续费中
`N`	本地已确认取消
`FAILED`	CREATE 提交失败
`NOT_FOUND`	找不到会员记录
`UNSUPPORTED`	不支持的 cancelOperation
`ERROR`	异常

轮询建议

1. 调 CREATE (cancelOperation=0)
   ├─ bizCode=10201 → 进入轮询
   ├─ bizCode=10203 → 展示失败，结束
   └─ 其他 → 异常处理

2. 每隔 5-10 秒调 SELECT (cancelOperation=1)，最多轮询 6 次
   ├─ bizCode=10200 → 展示成功，结束
   ├─ bizCode=10203 → 展示失败，结束
   └─ bizCode=10201 → 继续轮询

轮询超时建议：达到最大轮询次数仍为 10201，提示用户「取消请求已提交，稍后查看结果」。

各场景响应示例

CREATE 场景

提交成功（PayPal 接受）

{
  "code": 200,
  "msg": "取消成功，X分钟后生效",
  "data": {
    "cancelOperation": 0,
    "paypalStatus": "204",
    "orderCancelStatus": "PENDING",
    "bizCode": 10201
  }
}

提交失败（PayPal 拒绝）

{
  "code": 500,
  "msg": "取消订阅提交失败",
  "data": {
    "cancelOperation": 0,
    "paypalStatus": "401",
    "orderCancelStatus": "FAILED",
    "bizCode": 10203
  }
}

SELECT 场景

已取消（回调已处理）

{
  "code": 200,
  "msg": "订阅已取消",
  "data": {
    "cancelOperation": 1,
    "paypalStatus": "CANCELLED",
    "orderCancelStatus": "N",
    "bizCode": 10200
  }
}

已取消（补偿触发，后端自动补单）

{
  "code": 200,
  "msg": "订阅已取消（补偿）",
  "data": {
    "cancelOperation": 1,
    "paypalStatus": "CANCELLED",
    "orderCancelStatus": "N",
    "bizCode": 10200
  }
}

处理中（PayPal 还没取消）

{
  "code": 200,
  "msg": "订阅取消中，等待paypal回调确认",
  "data": {
    "cancelOperation": 1,
    "paypalStatus": "ACTIVE",
    "orderCancelStatus": "Y",
    "bizCode": 10201
  }
}

找不到会员记录

{
  "code": 500,
  "msg": "找不到会员记录",
  "data": {
    "cancelOperation": 1,
    "paypalStatus": null,
    "orderCancelStatus": "NOT_FOUND",
    "bizCode": 10203
  }
}

公共场景

登录校验失败

{
  "code": 500,
  "msg": "<具体错误信息>",
  "data": null
}

subscriptionId 为空

{
  "code": 500,
  "msg": "订阅subscriptionId不能为空",
  "data": null
}

字段判空提醒

data.paypalStatus 在以下场景可能为 null，前端读取时需做空值容错：

找不到会员记录
不支持的操作类型
异常

CREATE 场景下 paypalStatus 为 PayPal 取消接口返回的 HTTP 状态码字符串（如 "204"、"401"）。
SELECT 场景下 paypalStatus 为 PayPal 订阅状态字符串（如 "CANCELLED"、"ACTIVE"、"SUSPENDED"）。

2026-04-28