绑卡开户

绑卡+开户 `POST /v1/wallet/account/open`

用途：校验商户 一键绑卡 产品后，向宝付申请前台绑卡链接；用户完成绑卡后，系统异步完成开户/绑卡收敛；成功后推送 OPEN_ACCOUNT_SUCCESS 异步通知。

分支说明

场景	行为
未开户	申请宝付绑卡链接，返回 `walletBizNo` + 链接字段
已开户	不发起绑卡，同步返回 `accountOpened=true` 及账户信息；无 `walletBizNo`；追加绑卡请调 §单独绑卡接口bind-only

Body 字段说明

字段	类型	必填	最大长度	说明
`merchantId`	string	条件	32	商户直连必填，且与 `Authorization` 中 `mch_id` 一致；统一会员可省略
`terminalId`	string	条件	32	商户直连必填；统一会员可省略
`merchantRequestNo`	string	是	64	商户请求流水号；幂等键：`merchantId + merchantRequestNo`
`cardHolderName`	string	是	10	持卡人姓名
`idCardNo`	string	是	32	证件号
`idCardType`	string	是	16	证件类型，如 `ID_CARD`
`mobile`	string	是	20	手机号
`pageUrl`	string	是	512	用户绑卡完成后浏览器回跳地址
`notifyUrl`	string	是	512	绑卡/开户终态异步通知地址（HTTPS）
`ext`	string	否	—	扩展 JSON 字符串（预留）

请求示例（未开户）

{
  "merchantId": "M100001",
  "terminalId": "T10001",
  "merchantRequestNo": "MCH202505250001",
  "cardHolderName": "张三",
  "idCardNo": "310101199001011234",
  "idCardType": "ID_CARD",
  "mobile": "13800138000",
  "pageUrl": "https://merchant.example.com/bind/return",
  "notifyUrl": "https://merchant.example.com/callback/wallet/bind"
}

响应体字段说明（resBody / body）

按 accountOpened 分两种返回，不会同时出现下表两组的全部字段。

A. 未开户 — 返回绑卡链接（商户需保存 walletBizNo 用于轮询）

字段	类型	说明
`merchantRequestNo`	string	商户请求流水号（与请求一致）；用于绑卡结果查询
`walletBizNo`	string	钱包业务号
`url`	string	cutpayment 前台入口（基础地址）
`token`	string	明文会话 token，用于 POST 提交打开绑卡页（见下「打开绑卡页」）
`expireTime`	string	链接过期时间，`yyyyMMddHHmmss`；轮询不宜超过此时点
`accountOpened`	boolean	固定 `false`

token 与数字信封（必读）：当前一期 一键绑卡 返回的 token 为明文，不需要 也不提供 dgtlEnvlp 解密（响应中无此字段或为空）。请勿按多绑/旧文档流程做数字信封解密。

B. 已开户 — 不发起绑卡，返回开户信息

字段	类型	说明
`merchantRequestNo`	string	商户请求流水号（与请求一致）
`accountOpened`	boolean	固定 `true`
`customerNo`	string	客户号
`contractNo`	string	签约号；功能三扣款、功能二追加绑卡使用
`createdAt`	string	开户时间，`yyyyMMddHHmmss`

已开户分支无 walletBizNo、无绑卡链接。追加绑卡请调 单独绑卡接口bind-only。

成功响应示例（未开户，返回绑卡链接）

{
  "merchantRequestNo": "MCH202505250001",
  "walletBizNo": "4001010120250525120000000001",
  "url": "https://cutpayment.example.com/protocol/onceOperationPageRedirect",
  "token": "a1b2c3d4e5f6789012345678abcdef01",
  "expireTime": "20260525153000",
  "accountOpened": false,
  "productType": "SINGLE_BIND"
}

示例中 productType 等为系统附带字段，对接可忽略。

成功响应示例（已开户）

{
  "merchantRequestNo": "MCH202505250001",
  "accountOpened": true,
  "customerNo": "CUS202605180001",
  "contractNo": "C20250525000001",
  "createdAt": "20260518090000"
}

商户打开绑卡页（与当前实现一致）

向返回的 url 以 POST 方式提交明文 token（连同 txn_type、send_time 等参数，与 cutpayment 一键绑卡前台约定一致；send_time 为发起提交时的当前时间）。
引导用户在浏览器完成 cutpayment 绑卡流程；pageUrl 用于绑卡完成后的前端回跳。
商户服务端轮询 绑卡结果查询，并配置 异步通知 作为兜底。

常见失败 code

code	说明
`TRADE_ERROR`	产品未开通、链接申请失败等
`INVALID_PARAMETER`	参数校验失败
`MERCHANT_NOT_FOUND`	商户鉴权失败
`SYSTEM_ERROR`	系统异常

绑卡开户

绑卡+开户 POST /v1/wallet/account/open

绑卡+开户 `POST /v1/wallet/account/open`