创建订阅 POST /v1/subscription/sign

Header 示例

Request-ID: req-20260319120000001
Baofu-Mch-ID: UM_NEW_10001
Baofu-Sign-Type: RSA
Mch-Serial-No: MCH_CERT_SERIAL_001
Baofu-Serial-No: BF_CERT_SERIAL_001
X-Forwarded-For: 203.0.113.10
Content-Type: application/json

Body 字段说明

字段 类型 必填 最大长度 说明
outTradeNo string 是 64 商户侧订单号；与 Baofu-Mch-ID 对应统一会员组成签约幂等键
productCode string 是 32 内部产品编码（配置中心维护）
userId string 视产品 64 用户标识
riskItem string 是 2048 风控扩展，JSON 字符串（内部 JSON 需转义）；详细参数见风控参数字段说明（通用参数、电商、互金消金、航旅、酒店、保险、游戏、大宗）；透传至协议支付，具体字段以运营对接为准
deductionPayRoute array 是 — 扣款路径，JSON 数组；至少一档，每档含 order、paymentMethod、subjectRef（协议号等主体引用）
notifyUrl string 视业务 512 异步通知地址，须以 http:// 或 https:// 开头；用于接收 第 2 章 所述回调
merchantNo string 否 32 商户号；可省略，以统一会员反查为准
clientIp string 否 128 客户端 IP；网关未解析到 IP 时可兜底，与订阅落库 client_ip 一致

注意：deductionPayRoute 为 JSON 数组类型，直接传 JSON 数组即可，无需做字符串转义；riskItem 仍为 String 类型，值为 JSON 字符串，必须对内部 JSON 做转义处理。

deductionPayRoute 内部 JSON 数组结构说明

字段 类型 必填 说明
order number 是 扣款路径优先级序号（从 1 开始，越小越优先）
paymentMethod string 是 支付方式，见 §3.5
subjectRef string 是 主体引用（如协议号）
ext object 否 扩展参数

请求示例

{
  "merchantNo": "M100001",
  "outTradeNo": "MCH202603190001",
  "productCode": "PC202603260001",
  "userId": "U10001",
  "riskItem": "{\"scene\":\"SUBSCRIPTION_SIGN\",\"deviceId\":\"dev-xxx\"}",
  "deductionPayRoute": [{"order":1,"paymentMethod":"PROTOCOL_CARD","subjectRef":"PRT20260319000001","ext":{}}],
  "notifyUrl": "https://merchant.example.com/callback/subscription"
}

响应 data 字段说明

成功时 data 为订阅视图对象，字段如下：

字段 类型 说明
subscriptionNo string 订阅号
merchantNo string 商户号（可空）
outTradeNo string 商户签约订单号
productCode string 内部产品编码
userId string 用户标识
cycleType string 周期类型，见 §3.3
cycleValue number 周期值
fixedDay number 固定扣款日（依周期模型）
baseAmount number 每期扣款基准金额（分）；与产品配置或营销算价结果一致
appliedPricingType string 应用的定价类型枚举码，见 §3.6
status string 订阅状态，见 §3.1
signTime string 签约时间
cancelTime string 取消时间（未取消时为 null）
nextDeductionTime string 下次计划扣款时间
currentPeriod number 当前期数
totalPeriod number 总期数；null 为永续

成功响应示例

{
  "success": true,
  "code": null,
  "message": null,
  "data": {
    "subscriptionNo": "SP01010120260319120000000001",
    "merchantNo": "M100001",
    "outTradeNo": "MCH202603190001",
    "productCode": "PC202603260001",
    "userId": "U10001",
    "cycleType": "MONTH",
    "cycleValue": 1,
    "fixedDay": null,
    "baseAmount": 1990,
    "appliedPricingType": null,
    "status": "ACTIVE",
    "signTime": "2026-03-19 12:00:00",
    "cancelTime": null,
    "nextDeductionTime": "2026-04-19 12:00:00",
    "currentPeriod": 1,
    "totalPeriod": 12
  }
}
  • 支付处理中：会返回业务码 SUB_003005（code），表示“结果未决、需查单确认”；不要据此直接当作签约失败或最终成功。

签约返回 SUB_003005 时的商户处理规范（强烈建议）

  1. 先记录本次 outTradeNo 与请求时间，前端提示“处理中”。
  2. 立即或短延迟（如 1~3 秒）调用 POST /v1/subscription/query（优先按 outTradeNo）查询订阅状态；必要时同时调用 POST /v1/subscription/deduction/query。
  3. 若状态仍为处理中（如 SUSPENDED / 扣款单 CHANNEL_PENDING），按固定间隔轮询（建议 35 秒，最多 12 分钟），超时后转人工或异步通知兜底。
  4. 收到异步通知后，以通知为准更新本地订单状态；通知与轮询结果不一致时，以“终态优先 + 幂等更新”处理。
  5. 以 outTradeNo（签约）与 deductionNo（扣款）做幂等键，避免重复发货/开通权益或重复扣费处理。