基本定义

  • 方法：POST
  • 路径：/v1/wallet/account/bind
  • Content-Type：application/json
  • Auth：统一网关
  • Timeout：5000ms（建议）
  • 幂等键：merchant_id + out_trade_no
  • 描述：已开户用户追加绑卡；未开户直接失败

请求字段

字段 类型 必填 约束 说明
out_trade_no string 是 最长 64 商户订单号
contract_no string 是 最长 32 签约号；来自开户查询
page_url string 是 最长 256 绑卡完成回跳地址
notify_url string 是 最长 256 异步通知地址（HTTPS）

请求示例：

{
  "out_trade_no": "MCH202505250002",
  "contract_no": "C20250525000001",
  "page_url": "https://merchant.example.com/bind/return",
  "notify_url": "https://merchant.example.com/callback/wallet/bind"
}

响应字段（成功受理）

字段 类型 必填 约束 说明
out_trade_no string 是 与请求一致 商户订单号
trade_no string 是 非空 平台交易号
contract_no string 是 非空 签约号
url string 是 URL 绑卡入口
token string 是 明文 会话 token
expire_time string 是 ISO 8601 链接过期时间

响应示例：

{
  "out_trade_no": "MCH202505250002",
  "trade_no": "4001010120250525120000000002",
  "contract_no": "C20250525000001",
  "url": "https://cutpayment.example.com/protocol/onceOperationPageRedirect",
  "token": "a1b2c3d4e5f6789012345678abcdef01",
  "expire_time": "2026-05-25T16:00:00+08:00"
}

错误与调用方处理

HTTP 网关 code 触发条件 调用方处理 可重试
200 — 受理成功 打开绑卡页；轮询 HTTP-003 或等 NOTIFY-001 否
非 200 INVALID_PARAMETER 参数校验失败；用户未开户；Header 缺失 先完成开户或修正参数 视情况
非 200 TRADE_ERROR 产品未开通；申请链接失败 换 out_trade_no 重试 视情况
非 200 ORDER_DUPLICATED 同 merchant_id + out_trade_no 幂等命中 查 HTTP-003；data 可含已有 trade_no 否
非 200 SYSTEM_ERROR 系统异常 稍后重试或查 HTTP-003 是