快速接入指南

0. 选定清结算模式

接入前先明确:订阅扣款由谁负责?

`settlementMode`	适用场景	接入路径
`CXH_DEDUCT`	由 CXH 完成绑卡与后续代扣,渠道仅关注订阅状态与权益发放	`auth → bind-sms → bind-confirm → orders/create → orders/query`
`CHANNEL_COLLECT`	渠道已具备自有支付体系,仅需 CXH 提供权益(退款由渠道自管,CXH 不参与)	`auth → orders/create(`settlementMode=CHANNEL_COLLECT`)→ orders/query`

两种模式可在同一渠道并存(不同 SPU 适用不同模式)。settlementMode 在 orders/create 入参中必填,创建后不可变更。

角色交互流程图

A · `CXH_DEDUCT`(以 A.1 自绑为主线,A.2 协议共享跳过绑卡步骤)

B · `CHANNEL_COLLECT`(渠道收单)

1. 准备凭据

由 BD 提供一次性密钥包:

appId          test_xxxxxxx                # 渠道唯一标识(测试 appId 通常以 test_ 前缀)
appSecret      base64 (32 bytes)           # HMAC-SHA256 签名密钥
aesKey         base64 (32 bytes)           # AES-256-CBC 字段加密密钥(仅 CXH_DEDUCT 使用)
callbackSecret base64 (32 bytes)           # 接收回调时验签

⚠ 密钥仅返回一次。请使用安全的密钥管理工具(团队密码管理器、KMS、加密配置中心等)保存,严禁明文落入代码或日志。如发生泄露请走重置流程,原密钥立即失效。

测试与生产密钥独立,互不通用:沙箱凭据仅可访问测试 base URL(测试库、测试 SPU、测试用户)。沙箱完成 E2E 联调验收后,BD 另发一套生产独立密钥(appId 不带 test_ 前缀)。两套密钥的 channel、SPU 授权、IP 白名单、限流、支付通道授权全部独立。生产开通前置条件参见 FAQ § 生产开通条件。

2. 调用约定

Base URL:沙箱 https://test-api.cxh.me,生产 https://api.cxh.me
所有业务接口 POST + application/json,UTF-8
请求带 5 个签名头部 + Authorization: Bearer <accessToken>(auth/token 除外)
响应统一封装为 { code, message, data, requestId, timestamp, success },code == "0" 才业务成功

完整规范(状态码用法 / 字段类型 / 时间金额格式 / 幂等 / 重试与超时 / Long 序列化为 String 等)见 HTTP 请求 / 响应规范;签名与加密细节见签名与字段加密。

3. 调用流程(伪代码,签名头部省略)

CXH_DEDUCT

[0] POST /openapi/v1/products/list           → 当前渠道授权的 SPU 列表(建议接入时缓存)
[1] POST /openapi/v1/auth/token              → accessToken
[2] POST /openapi/v1/agreements/bind-sms     → bindOrderNo + 短信下发
[3] POST /openapi/v1/agreements/bind-confirm → agreementNo + agreementStatus=BIND_SUCCESS
[4] POST /openapi/v1/orders/create           → orderNo + orderStatus(ACTIVE / INITIALIZING / TERMINATED)
                                                + 首期 paymentRecords[0].paymentStatus(SUCCESS / PROCESSING / FAIL)
                                                + redeemUrl(仅同步 SUCCESS 时有值)
[5] POST /openapi/v1/orders/query            → 主订单详情(异步路径需在收到 webhook 后再次查询以获取 redeemUrl)

CHANNEL_COLLECT

[0] POST /openapi/v1/products/list           → 当前渠道授权的 SPU 列表
[1] POST /openapi/v1/auth/token              → accessToken
[2] POST /openapi/v1/orders/create           → orderNo + 首期 paymentRecords[0](paymentStatus=BILLED,权益已发,可立即兑换)
[3] POST /openapi/v1/orders/query            → 主订单详情

渠道侧的退款由渠道自行处理,CXH 不参与、不感知;渠道侧退款不影响 CXH 已发权益。

4. 步骤语义

步骤	动作	主要返回
products/list	拉取当前渠道授权的 SPU 列表(周期、期数、单期价格由 CXH 预设)	SPU 列表
auth/token	client_credentials 模式获取 token,有效期 2 小时	accessToken
bind-sms(仅 A)	提交绑卡四要素,通道下发短信	bindOrderNo + agreementStatus=BIND_ING
bind-confirm(仅 A)	用户输入短信码,协议生效	agreementNo + agreementStatus=BIND_SUCCESS
orders/create · A	创建订阅,同步触发首扣(返回时已为首扣结果)	orderNo + orderStatus(INITIALIZING / ACTIVE / TERMINATED)+ paymentStatus(SUCCESS / PROCESSING / FAIL)
orders/create · B	创建订阅,立即开账,立即发放权益	orderNo + orderStatus=ACTIVE + paymentStatus=BILLED
orders/query	查询主订单、期次列表与累计退款(只读)	订单详情

A 模式退款由 CXH 内部审核处理(渠道侧通过合同流程联系 BD 提交申请);B 模式退款由渠道自管,CXH 不感知。refundAmountCent / totalRefundAmountCent 字段在 A 模式查询响应中可见;B 模式始终为 0。

5. 沙箱触发字段

沙箱(test-api.cxh.me)与生产(api.cxh.me)使用同一套 open API,沙箱接通后切生产无需修改渠道代码。沙箱根据请求中特定字段的值返回预设结果(见下表),触发值仅沙箱有效;生产按实际交易处理。沙箱不真实扣款、不真实发短信、不真实发放卡密 / 充值;用户层面的完整验证请在生产完成。建议跑一次 externalOrderNo 以 _PENDING 结尾的下单(同步返 PENDING + 30 秒后推 payment.status.changed),验证渠道侧 webhook 接收、验签与幂等。

接口 / 场景	模式	触发字段	行为
`agreements/bind-sms`	A	`bankMobile` 末位 `9`	SMS 失败(`smsStatus=SEND_FAIL`)
`agreements/bind-sms`	A	其他	SMS 发送成功
`agreements/bind-confirm`	A	`smsCode == "000000"`	绑卡失败 `BIND_FAIL`
`agreements/bind-confirm`	A	其他任意码(如 `123456`)	绑卡成功
`orders/create` 触发的首扣	A	`externalOrderNo` 以 `_FAIL` 结尾	首扣终态失败,主订单 `TERMINATED`,不发权益
`orders/create` 触发的首扣	A	`externalOrderNo` 以 `_FAIL_RETRY` 结尾	通道层可重试失败;首扣按终态失败返回 `FAIL`,主订单 `TERMINATED`
`orders/create` 触发的首扣	A	`externalOrderNo` 以 `_PENDING` 结尾	同步返 `PROCESSING`,30 秒后异步回调 SUCCESS,推 `payment.status.changed`
`orders/create` 触发的首扣	A	其他	立即 SUCCESS,首期权益发放
续扣(CXH 自动触发,无渠道接口)	A	—	一律 SUCCESS。如需联调续扣失败 / 异步用例,联系 BD 在沙箱后台预置该期
`orders/create`	B	—	立即 BILLED,首期权益发放
`orders/unsubscribe`	A / B	—	解约成功,后续期不再扣款

6. 常用 productCode(沙箱预置)

可选 SPU 由 BD 为渠道授权,实际请调用 products/list 获取。沙箱常见预置:

productCode	描述	周期 / 期数 / 单期价
`TEST_SPU_001`	联调主用会员 SPU(月卡 12 期)	`MONTH × 1 / 12 期 / 19.90 元`
`TEST_SPU_DAILY_7`	高频测试 SPU(日卡 7 期)	`DAY × 1 / 7 期 / 1.00 元`

申请新 SPU 或修改价格请联系 BD。

7. 下一步

接口字段详见 API 接口(按模块分类)
生产前必须实现回调接收,详见回调通知
错误码用法详见错误码
常见问题详见 FAQ

快速接入指南 ​

0. 选定清结算模式 ​

角色交互流程图 ​

A · CXH_DEDUCT(以 A.1 自绑为主线,A.2 协议共享跳过绑卡步骤) ​

B · CHANNEL_COLLECT(渠道收单) ​

1. 准备凭据 ​

2. 调用约定 ​

3. 调用流程(伪代码,签名头部省略) ​

CXH_DEDUCT ​

CHANNEL_COLLECT ​

4. 步骤语义 ​

5. 沙箱触发字段 ​

6. 常用 productCode(沙箱预置) ​

7. 下一步 ​