签约

商户发起订阅签约，含首期扣款或试用鉴权。扣款路径中的 payment_protocol_no 须先通过绑卡（预绑确认、绑卡查询或 190 H5 通知）取得。Timeout 建议 15s；幂等键 out_trade_no。

接口说明

请求方式：【POST】/v1/subscription/sign

请求域名：【主域名】https://api.baofu.com

请求参数

Header 参数

参数名	类型	必填	描述
Authorization	string	true	请参考【开发指引-整体说明】生成认证信息
Accept	string	true	请设置为 `application/json`
Content-Type	string	true	请设置为 `application/json`

Body 参数

参数名	类型	必填	描述
out_trade_no	string(64)	true	商户订单号
product_code	string(32)	true	产品编码
merchant_user_id	string(64)	false	【用户标识】视产品是否要求上送
risk_control_info	string(2048)	true	【风控参数】JSON 字符串
deduction_pay_route	array[object]	true	【扣款路径】至少 1 条。敏感字段，须数字信封整段加密：明文为 JSON 数组；实际上送为密文字符串
notify_url	string(512)	false	【异步通知地址】需接收异步通知时上送
payer_client_ip	string(128)	false	客户端 IP
deduction_pay_route.bind_order	integer	true	路由优先级（升序尝试）
deduction_pay_route.pay_method	string	true	支付方式，如 `PROTOCOL_CARD`
deduction_pay_route.payment_protocol_no	string	true	协议号/主体引用（来自绑卡确认、查询或 H5 通知；随 `deduction_pay_route` 整段数字信封加密，不单独加密本字段）
deduction_pay_route.ext	object	false	扩展参数

请求示例

加密前明文；实际上送时 deduction_pay_route 为密文字符串

{
  "out_trade_no": "MCH202603190001",
  "product_code": "PC202603260001",
  "merchant_user_id": "U10001",
  "risk_control_info": "{\"scene\":\"SUBSCRIPTION_SIGN\",\"device_id\":\"dev-xxx\"}",
  "deduction_pay_route": [
    {
      "bind_order": 1,
      "pay_method": "PROTOCOL_CARD",
      "payment_protocol_no": "PRT20260319000001",
      "ext": {}
    }
  ],
  "notify_url": "https://merchant.example.com/callback/subscription",
  "payer_client_ip": "203.0.113.10"
}

应答参数

200 OK

参数名	类型	必填	描述
subscription_no	string	true	订阅号
out_trade_no	string	true	商户签约订单号
product_code	string	true	产品编码
merchant_user_id	string	false	用户标识（可空）
period_type	string	true	周期类型，如 `MONTH`
period_value	integer	true	周期值
fixed_day	integer	false	固定扣款日（可空）
period_amount	integer	true	每期扣款金额（分）
applied_pricing_type	string	false	营销定价类型（可空），如 `FIRST_PERIOD_DISCOUNT`
subscription_status	string	true	订阅状态，如 `ACTIVE`
sign_time	string	true	签约时间，ISO 8601
cancel_time	string	false	取消时间，ISO 8601（可空）
next_deduction_time	string	false	下次计划扣款时间，ISO 8601（可空）
deduct_period	integer	true	扣款期数
total_period	integer	false	总期数（可空）

应答示例

200 OK

{
  "subscription_no": "SP01010120260319120000000001",
  "out_trade_no": "MCH202603190001",
  "product_code": "PC202603260001",
  "merchant_user_id": "U10001",
  "period_type": "MONTH",
  "period_value": 1,
  "fixed_day": null,
  "period_amount": 1990,
  "applied_pricing_type": "FIRST_PERIOD_DISCOUNT",
  "subscription_status": "ACTIVE",
  "sign_time": "2026-03-19T12:00:00+08:00",
  "cancel_time": null,
  "next_deduction_time": "2026-04-19T12:00:00+08:00",
  "deduct_period": 1,
  "total_period": 12
}

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数校验失败	必填参数缺失或格式不合法
401	SIGN_ERROR	验证不通过	请参阅【开发指引-整体说明】排查签名
500	SYSTEM_ERROR	系统异常	内部系统错误

业务错误码

状态码	错误码	描述	解决方案
409	ORDER_DUPLICATED	重复请求	`out_trade_no` 幂等命中
402	USER_PAYING	结果未决	首期支付处理中
402	TRADE_ERROR	业务失败	渠道失败或业务拒绝

应答示例

失败

{
  "code": "USER_PAYING",
  "message": "支付处理中"
}