Appearance
订阅查询
三个只读接口:主订单详情(含期次列表)/ 渠道用户订阅列表 / 单期子订单详情。 返回结构对
CXH_DEDUCT/CHANNEL_COLLECT两种模式通用,差异通过settlementMode与paymentStatus区分(BILLED仅用于 B 模式,详见 字段约定)。refundAmountCent/totalRefundAmountCent仅 A 模式有意义(CXH 内部退款时回写)。B 模式 CXH 不参与退款,这两个字段在返回中始终为 0。
POST /openapi/v1/orders/query
按 CXH 单号或渠道单号查询主订单详情。
请求
orderNo 与 externalOrderNo 二选一:
json
{ "orderNo": "SUB..." }json
{ "externalOrderNo": "ext_xxx" }响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
orderNo | string | CXH 主订单号 |
externalOrderNo | string | 渠道主订单号 |
createTime | string | 订单创建时间(yyyy-MM-dd HH:mm:ss) |
orderStatus | string | INITIALIZING / ACTIVE / UNSUBSCRIBED / COMPLETED / TERMINATED,详见 字段约定 |
orderSuccessTime | string | 主订单首次激活(转 ACTIVE)的时间 |
periodType | string | DAY / MONTH |
period | int | 周期单位倍率 |
totalCycles | int | 总期数 |
totalPaidAmountCent | long | 累计用户侧支付金额(分);B 模式为已 BILLED 期次对应的用户侧 SPU 金额累计 |
totalRefundAmountCent | long | 累计退款金额(分);B 模式始终为 0 |
nextPayTime | string | null | 下次扣款 / 开账时间;订单完结或解约后为 null |
unsubscribeTime | string | null | 解约时刻;orderStatus != UNSUBSCRIBED 时为 null |
redeemUrl | string | null | 兑换入口 URL;详见下方说明 |
paymentRecords | array | 期次列表;字段见下方 PaymentRecord |
json
{
"orderNo": "SUB...",
"externalOrderNo": "ext_xxx",
"createTime": "2026-04-28 12:00:00",
"orderStatus": "ACTIVE",
"orderSuccessTime": "2026-04-28 12:00:01",
"periodType": "MONTH",
"period": 1,
"totalCycles": 12,
"totalPaidAmountCent": 1990,
"totalRefundAmountCent": 0,
"nextPayTime": "2026-05-28 12:00:00",
"unsubscribeTime": null,
"redeemUrl": "https://<cxh-h5>/redeem?orderNo=SUB...&appId=test_xxx&channelUserId=u_001&exp=1714003200&sig=xxx",
"paymentRecords": [
{
"paymentOrderNo": "PAY...",
"cycleNo": 1,
"expectPayTime": "2026-04-28 12:00:00",
"paidAt": "2026-04-28 12:00:01",
"amountCent": 1990,
"refundAmountCent": 0,
"paymentStatus": "SUCCESS"
}
]
}PaymentRecord 字段
| 字段 | 类型 | 说明 |
|---|---|---|
paymentOrderNo | string | 子订单号 |
cycleNo | int | 期次序号(从 1 开始) |
expectPayTime | string | 计划扣款 / 开账时刻 |
paidAt | string | null | 实际扣款 / 开账成功时刻;失败为 null |
amountCent | long | 本期用户侧支付金额(分);B 模式为渠道向用户收取的 SPU 单期金额 |
refundAmountCent | long | 本期已退款金额(分);B 模式始终为 0 |
paymentStatus | string | WAIT / PROCESSING / SUCCESS / FAIL_RETRY / FAIL / BILLED / CANCELED / REFUND_*;详见 字段约定 |
B 模式(CHANNEL_COLLECT)响应示例(paymentStatus=BILLED,paidAt 表示开账成功时刻,amountCent 为用户侧 SPU 单期金额,refundAmountCent 始终为 0):
json
{
"orderNo": "SUB...",
"externalOrderNo": "ext_xxx",
"createTime": "2026-04-28 12:00:00",
"orderStatus": "ACTIVE",
"orderSuccessTime": "2026-04-28 12:00:01",
"periodType": "MONTH",
"period": 1,
"totalCycles": 12,
"totalPaidAmountCent": 1990,
"totalRefundAmountCent": 0,
"nextPayTime": "2026-05-28 12:00:00",
"unsubscribeTime": null,
"redeemUrl": "https://<cxh-h5>/redeem?orderNo=SUB...&appId=test_xxx&channelUserId=u_001&exp=1714003200&sig=xxx",
"paymentRecords": [
{
"paymentOrderNo": "PAY...",
"cycleNo": 1,
"expectPayTime": "2026-04-28 12:00:00",
"paidAt": "2026-04-28 12:00:01",
"amountCent": 1990,
"refundAmountCent": 0,
"paymentStatus": "BILLED"
}
]
}
redeemUrl字段:订阅当前存在"已发未消耗"权益时返回(每次查询exp重新计算+7d)。A 模式仅在首扣SUCCESS后返回,其他状态(WAIT/PROCESSING/FAIL_RETRY/FAIL)及全部期次已退完时均为null。生成与签名规则见 订阅下单 § redeemUrl。
unsubscribeTime字段:订阅已解约(orderStatus=UNSUBSCRIBED)时返回解约时刻;未解约时为null。
POST /openapi/v1/orders/list
按渠道用户列出全部订阅。
请求
| 字段 | 必填 | 说明 |
|---|---|---|
channelUserId | ✓ | 渠道侧用户唯一 ID |
cycleType | — | SINGLE(单周期 SPU) / MULTIPLE(多周期 SPU);不传返回该用户全部订阅 |
json
{
"channelUserId": "u_001"
}响应 data
外层包一层 orders 数组,元素结构与 orders/query 响应一致。
json
{
"orders": [
{ "orderNo": "SUB...", "orderStatus": "ACTIVE", "...": "..." },
{ "orderNo": "SUB...", "orderStatus": "UNSUBSCRIBED", "...": "..." }
]
}POST /openapi/v1/payments/query
按 paymentOrderNo 查询单期子订单详情。orders/query 已返回完整 paymentRecords 列表,本接口用于按单期定向查询。
请求
| 字段 | 必填 | 说明 |
|---|---|---|
paymentOrderNo | ✓ | 子订单号 |
json
{ "paymentOrderNo": "PAY..." }响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
paymentOrderNo | string | 子订单号 |
orderNo | string | 主订单号 |
externalOrderNo | string | 渠道主订单号 |
cycleNo | int | 期次序号(从 1 开始) |
expectPayTime | string | 计划扣款 / 开账时刻 |
paidAt | string | null | 实际扣款 / 开账成功时刻 |
amountCent | long | 本期用户侧支付金额(分);B 模式为渠道向用户收取的 SPU 单期金额 |
usedAmountCent | long | 本期已被权益消耗的金额(分) |
refundTime | string | null | 退款时刻;无退款时 null |
refundAmountCent | long | 累计退款金额(分);B 模式始终为 0 |
paymentStatus | string | 见 字段约定 § paymentStatus |
claimRecords | array | 该期已发权益的领取记录;预留字段 |
json
{
"paymentOrderNo": "PAY...",
"orderNo": "SUB...",
"externalOrderNo": "ext_xxx",
"cycleNo": 1,
"expectPayTime": "2026-04-28 12:00:00",
"paidAt": "2026-04-28 12:00:01",
"amountCent": 1990,
"usedAmountCent": 0,
"refundTime": null,
"refundAmountCent": 0,
"paymentStatus": "SUCCESS",
"claimRecords": []
}字段含义见 字段约定。