绑卡开户H5

基本定义

方法：POST
网关路径：/v1/wallet/h5/multi
Content-Type：application/json
Auth：统一网关
Timeout：5000ms（建议）
幂等键：merchant_id + out_trade_no
描述：申请H5 页面链接；未开户时返回 url，商户可直接跳转；已开户时短路返回账户信息。

请求字段

字段	类型	必填	约束	说明
`out_trade_no`	string	是	最长 64	商户订单号
`real_name`	string	是	最长 128	姓名
`identity_document_no`	string	是	最长 64	证件号
`identity_document_type`	string	是	最长 16；如 `ID_CARD`	证件类型
`mobile`	string	是	最长 20；手机号格式	手机号
`page_url`	string	是	最长 256；URL	用户绑卡完成后回跳地址
`notify_url`	string	是	最长 256；HTTPS URL	绑卡/开户终态异步通知地址

请求示例：

{
  "out_trade_no": "MCH202505250010",
  "real_name": "张三",
  "identity_document_no": "310101199001011234",
  "identity_document_type": "ID_CARD",
  "mobile": "13800138000",
  "page_url": "https://merchant.example.com/h5/bind/return",
  "notify_url": "https://merchant.example.com/callback/wallet/bind"
}

响应字段（分支 A：未开户，返回 H5 绑卡链接）

触发：account_opened=false；成功申请多绑 H5 链接。

字段	类型	必填	约束	说明
`out_trade_no`	string	是	与请求一致	商户订单号
`trade_no`	string	是	非空	平台交易号；须保存用于查单
`url`	string	是	URL	多绑 H5 完整入口链接
`expire_time`	string	是	ISO 8601	链接过期时间
`account_opened`	boolean	是	固定 `false`	是否已开户

响应示例：

{
  "out_trade_no": "MCH202505250010",
  "trade_no": "4001010120250525120000000010",
  "url": "https://cutpayment.example.com/protocol/multiBindPageRedirect?token=a1b2c3d4e5f6789012345678abcdef10",
  "expire_time": "2026-05-25T15:30:00+08:00",
  "account_opened": false
}

响应字段（分支 B：已开户，返回账户信息）

触发：account_opened=true；不返回 H5 链接。

字段	类型	必填	约束	说明
`out_trade_no`	string	是	与请求一致	商户订单号
`account_opened`	boolean	是	固定 `true`	是否已开户
`customer_no`	string	是	非空	客户号
`contract_no`	string	是	非空	签约号
`create_time`	string	是	ISO 8601	开户时间

响应示例：

{
  "out_trade_no": "MCH202505250010",
  "account_opened": true,
  "customer_no": "CUS202605180001",
  "contract_no": "C20250525000001",
  "create_time": "2026-05-18T09:00:00+08:00"
}

错误与调用方处理

HTTP	业务码（示例）	触发条件	调用方处理	可重试
`200`	—	未开户 H5 链接受理 / 已开户短路	跳转 `url` 或展示账户信息	否
非 `200`	`INVALID_PARAMETER`	参数或 Header 错误	修正后重试	是
非 `200`	`TRADE_ERROR`	产品未开通、H5 链接申请失败	开通产品或换 `out_trade_no`	视情况
非 `200`	`ORDER_DUPLICATED`	幂等命中	换 `out_trade_no` 或查 HTTP-003	否
非 `200`	`SYSTEM_ERROR`	系统异常	稍后重试	是