1.1 通用约定

Base URL（示例）

生成环境：https://api.baofu.com
测试环境：http://10.254.94.155:8080

实际前缀以环境配置为准；下列路径均为经 统一网关 暴露的 相对路径（版本前缀 v1）。

必选 Header
详细请参考【开发指引-整体说明】

Header 必填 说明
Authorization 是 统一网关鉴权；签名算法与签名参数见下表（须在一行内，勿换行）
Content-Type 是 固定 application/json

Authorization 签名信息

格式：Authorization: {签名算法} 参数名="参数值",...（{签名算法} 如 RSA、SM2）

参数名 说明
mch_id 宝付分配的唯一商编
app_id 宝付终端号；选填。若传值，则使用宝付 4.0 证书（商户直连）
nonce_str 请求随机串；须与构造签名串时使用的随机串一致
timestamp 时间戳；须与构造签名串时使用的时间戳一致
serial_no 商户 API 证书序列号，用于声明所使用的证书
baofu_serial_no 宝付证书序列号；联系技术支持获取
dgtl_envlp 数字信封（非必填）；16 位密钥，用宝付公钥加密后传输
signature 签名值

注意：以上签名信息项无顺序要求；dgtl_envlp 可为空。

Authorization 示例（须为单行；排版换行仅作展示）

Authorization: RSA mch_id="128308",app_id="128308",nonce_str="P7X2R9Z1M5W6Q4V3B8C0D2E1F7G9H2J4",signature="DKLJASKLFGHQWJFPWQJLFKGDKSLGJPQJPFWQJLGKNDLSKJGLDSJLKFSJAKL",timestamp="1507488238",serial_no="123821002",baofu_serial_no="123822342",dgtl_envlp="GLKUIOWQGKDLSNGLKQWJPRQ"
Content-Type: application/json

mch_id 取值（必读）

场景 判定条件 mch_id 填什么
商户直连 / 4.0 会员 Authorization 中传 app_id 4.0 商户号，与 Body merchantId 相同
统一会员 Authorization 中不传 app_id 统一会员编号（非商户号）；系统反查得到实际 merchantId/terminalId

简记：有 app_id → mch_id = 商户号；无 app_id → mch_id = 统一会员号。

接入模式

模式 条件 mch_id Body merchantId / terminalId
商户直连（4.0） Authorization 传 app_id 商户号（与 merchantId 一致） 必填；须与 mch_id 一致；terminalId 商户传入
统一会员 Authorization 不传 app_id 统一会员编号 可省略；由系统反查后用于下游

Body 原则

  • 业务参数使用 驼峰 命名。
  • 时间字段（应答 resBody 与异步通知 Body）：统一 yyyyMMddHHmmss（14 位）；请求鉴权 Authorization 内 timestamp 为秒级 Unix 时间戳。
  • 商户直连：mch_id = 商户号；Body merchantId 须与其一致，否则 MERCHANT_NOT_FOUND；terminalId 由商户传入。
  • 统一会员：mch_id = 统一会员号；Body 可不传 merchantId/terminalId。
  • 签名、验签、加解密、IP 白名单、限流由 统一网关 处理。

Body 字段「必填」列含义

列值 含义
是 缺失即返回 INVALID_PARAMETER
否 可选
条件 见字段说明中的分支条件

绑卡入口 open-with-bind / bind-only 均须 cardHolderName、idCardNo、idCardType、mobile、pageUrl、notifyUrl。

商户侧应答（网关出站）

字段 类型 说明
resHeaders object HTTP 响应头（含网关应答签名信息，用于验签；格式以统一网关规范为准）
resBody string 业务 JSON 字符串（验签、落库以该原始串为准）
body object 可选；部分 SDK 将 resBody 解析后的对象，字段与 resBody 相同

重要：下文各接口「响应示例」均为 resBody / body 的业务内容，不包含 { success, code, message, data } 外壳。

返回字段说明原则：各接口 仅列出商户对接需关注和使用的字段。实际 JSON 可能还包含其他字段（如 productType、origMsgId、functionType、扣款流水号等），可忽略，不影响对接。

业务成功如何判断（同步查询/受理成功）

  • HTTP 200
  • 解析 resBody（或 body）后，按各接口业务字段判断（如 bindStatus=SUCCESS、deductStatus=SUCCESS）
  • 不要在 resBody 内查找 success 字段

业务失败 / 处理中

场景 商户如何识别 resBody / body 内容
参数校验、鉴权失败等 网关/SDK 返回 code（如 INVALID_PARAMETER）、message；resBody 可能为空 以联调为准
绑卡/扣款结果查询 处理中 网关/SDK code=USER_PAYING（若提供）；resBody 内为进度对象 bindStatus=PROCESSING 等
绑卡/扣款结果查询 终态失败 HTTP 200；看 bindStatus / deductStatus=FAIL 及 failCode 业务 JSON
绑卡/扣款结果查询 终态成功 HTTP 200；看 bindStatus / deductStatus=SUCCESS 业务 JSON

响应示例（业务体，成功受理）

{
  "walletBizNo": "4001010120250525120000000001",
  "url": "https://cutpayment.example.com/protocol/onceOperationPageRedirect",
  "origMsgId": "20250525120000001"
}

同步业务失败（code 由网关/SDK 返回，非 resBody 内字段）

code message（示例）
INVALID_PARAMETER 参数校验失败说明
MERCHANT_NOT_FOUND 商户鉴权失败

处理中（绑卡）

绑卡类终态由系统 异步处理 完成；入口通常同步返回绑卡链接。商户应以 绑卡结果查询 + 异步通知 获取终态；查询处理中时 code=USER_PAYING（网关/SDK 元数据），resBody 内仍返回当前进度（含 bindStatus=INIT/PROCESSING）。

绑卡链接超过有效期将关单失败（failCode 如 WF_004003，failMessage「绑卡链接已过期」）。