订阅签约

接口说明

  • 适用场景：商户发起订阅签约，含首期扣款或试用鉴权
  • 方法：POST
  • 路径：/v1/subscription/sign
  • Timeout：建议 15s
  • 幂等键：out_trade_no

请求字段

字段 类型 必填 约束 匹配后（key / 中文名） 说明
out_trade_no string 是 ≤64 out_trade_no / 商户订单号 商户订单号
product_code string 是 ≤32 product_code / 产品码 产品编码
merchant_user_id string 视产品 ≤64 merchant_user_id / 商户用户 ID 用户标识
risk_control_info string 是 ≤2048 risk_control_info / 风控参数 风控参数 JSON 字符串
deduction_pay_route array 是 至少 1 条 deduction_route_list / 扣款路径列表 扣款路径
notify_url string 视业务 ≤512 notify_url / 商户回调地址 异步通知地址
payer_client_ip string 否 ≤128 payer_client_ip / 用户终端 IP 客户端 IP

deduction_pay_route[]：

字段 类型 必填 匹配后（key / 中文名） 说明
bind_order integer 是 bind_order / 扣款顺序 路由优先级（升序尝试）
pay_method string 是 pay_method / 支付方式 支付方式（见 1.5）
payment_protocol_no string 是 payment_protocol_no / 支付协议号 协议号/主体引用
ext object 否 extension / 通用扩展字段 扩展参数

请求示例：

{
  "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"
}

响应字段（成功）

字段 类型 必填 匹配后（key / 中文名） 说明
subscription_no string 是 subscription_no / 订阅号 订阅号
out_trade_no string 是 out_trade_no / 商户订单号 商户签约订单号
product_code string 是 product_code / 产品码 产品编码
merchant_user_id string 否 merchant_user_id / 商户用户 ID 用户标识
period_type string 是 period_type / 周期类型 周期类型
period_value integer 是 period_value / 周期值 周期值
fixed_day integer 否 fixed_day / 固定扣款日 固定扣款日
period_amount integer 是 period_amount / 每期扣款金额 每期扣款金额（分）
applied_pricing_type string 否 applied_pricing_type / 营销定价类型 营销定价类型
subscription_status string 是 subscription_status / 订阅状态 订阅状态
sign_time string 是 sign_time / 签约时间 签约时间
cancel_time string 否 cancel_time / 取消时间 取消时间
next_deduction_time string 否 next_deduction_time / 下次扣款时间 下次计划扣款时间
deduct_period integer 是 deduct_period / 扣款周期数 扣款期数
total_period integer 否 total_period / 总期数 总期数

响应示例（成功）：

{
  "subscription_no": "SP01010120260319120000000001",
  "out_trade_no": "MCH202603190001",
  "product_code": "PC202603260001",
  "merchant_user_id": "U10001",
  "period_type": "MONTH",
  "period_value": 1,
  "period_amount": 1990,
  "subscription_status": "ACTIVE"
}

响应示例（失败）：

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

错误与调用方处理

HTTP code 触发条件 调用方处理
200 — 签约成功 保存 subscription_no 与状态
非 200 USER_PAYING 首期支付处理中（业务码 SUB_003005） 轮询 HTTP-005/006 或等待通知
非 200 ORDER_DUPLICATED out_trade_no 幂等命中 按原单号查单，不重复提交
非 200 INVALID_PARAMETER 参数校验失败 修正参数后重试
非 200 TRADE_ERROR 渠道失败/业务失败 结合 message 处理

##