1. 文档说明

1.1 文档目的

本文档是交易集中入口的说明文档。本文档主要介绍入口参数公共参数部分。具体业务部分的参数，参见具体的接口文档说明。接口入口参数=公共参数+业务服务参数

1.2 阅读对象

  • 接口对接开发人员、维护人员和管理人员

1.3 术语与定义

1.3.1 符号含义

序号 符号缩写 符号性质 符号说明
1 M 强制域(Mandatory) 必须填写的属性，否则会被认为格式错误
2 C 条件域(Conditional) 某条件成立时必须填写的属性
3 O 选用域(Optional) 选填属性
4 R 原样返回域(Returned) 必须与先前报文中对应域的值相同的域

1.3.2 术语含义

  • 商户号： 宝付提供给商户的唯一编号，是商户在宝付的唯一标识；

2. 统一入口说明

2.1 请求地址

api类接口

  • 测试环境地址：https://vgw.baofoo.com/union-gw/apiv3/{服务编号}/transReq.do
  • 正式环境地址：https://public.baofu.com/union-gw/apiv3/{服务编号}/transReq.do

文件类接口

  • 测试环境地址：https://vgw.baofoo.com/union-gw/apiv3/{服务编号}/upload.do
  • 正式环境地址：https://public.baofu.com/union-gw/apiv3/{服务编号}/upload.do

提交方式： POST
请求体以表单形式传输，响应体是JSON格式的数据。

2.2 加解密说明

api接口请求加密

verifyType值 签名方式 敏感字段加密方式
10 (国密) 1. 原始串(header+body拼接)转换成UTF-8字节数组
2. 使用商户号作为用户ID,用商户私钥进行SM2签名
3. 签名结果转换成16进制字符串		 1. 生成16位key
2. 将key作为密钥和向量进行sm4加密(SM4/ECB/PKCS5Padding)
3. 加密结果转成16进制
11 (RSA) 1. 原始串(header+body拼接)转换成UTF-8字节数组
2. 用商户私钥进行RSA签名
3. 签名结果转换成16进制字符串		 1. 生成16位key
2. 将key作为密钥和向量进行aes加密(AES/CBC/NoPadding)
3. 加密结果转成16进制

例如header为 {“a”:”123”,”b”:”456”},body为{“c”:”789”}
则原始签名串为header+body:
{“a”:”123”,”b”:”456”}{“c”:”789”}

2.3 请求报文

请求参数

序号 域名 变量名 必填 备注
01 请求头 header M 请求的基础信息
02 请求体 body M 具体的业务报文
03 签名 sign M 签名 head+body进行签名

header部分

序号 域名 变量名 必填 备注
01 商户号 parentUid M 宝付分配给商户的唯一编码
02 报文发送时间 timestamp M yyyy-MM-dd HH:mm:ss
03 字符集 charset M 固定值:UTF-8
04 版本号 version M 固定值 1.0
05 加密方式 verifyType M 10(SM2),11(RSA)
06 签名证书序列号 signSn M 商户的签名证书序列号
07 加密证书序列号 ncrptnSN M 宝付的加密证书序列号,请联系技术支持获取
08 数字信封 dgtlEnvlp C 16位密钥,Base64转码后使用宝付的公钥加密
如有字段需要加密,则必传
09 加密参数名 encryptParams O 如有字段需要加密,则必传,服务端会按照此字段解密业务报文
场景1: 需要加密全报文,传$,服务端会全报文解密
场景2: 部分字段加密,传字段名,用逗号分隔
例如传a,b,c 那么服务端会对报文body部分的a,b,c3个字段进行解密。
此字段需要Base64转码
10 文件sha256值 sha256 C 调用文件相关接口必传，服务端会校验文件sha256值

body部分
参考具体业务接口的请求报文参数

请求报文示例
注意这里是form表单形式

[header={"charset":"UTF-8","dgtlEnvlp":"042DF505E841E731CB96DEBD1B656084BE4FFC2055080DE8532CADAF27F4E2AF78D01D4237677CD0D2D31A9A7BEB6E961036F0739B766D789F1D4F652E67CA3EB06ABD5CDA07D9EA8E910A3CED1FD9D5E121909038105D9DC9DCF99E92F1FBE42E3362F88102F26FF6D26437D37B0E95A7","encryptParams":"Y2xpZW50TWFj","ncrptnSN":"4026170978","parentUid":"13030918","sha256":"c230e53e7339d3666861b1ab20f8b68b2e37133cf858f414f80c3c3528f13f6a","signSN":"1387287848","timestamp":"2025-04-30 15:10:54","verifyType":"10","version":"1.0"}, body={"bankType":"SSQY-MC","clientIp":"172.23.120.148","clientMac":"654EE6E9D646ABC8A382F4AEC9A4B4BD","fileType":"DOOR_PHOTO","uid":"13030918"}, sign=3046022100A2459513FAE50F9153FD098A5C258526DA7982C510288FE5F23B75EE04336993022100C3D8A41E91A44EF536A6E23867881BC0A942847748C368AB24F55AC21CA9BF66]

2.4 同步响应报文

{
    "body": "{\"code\":\"000000\",\"message\":\"响应成功\",\"data\":{\"fileId\":\"52095713954680\",\"bankFileId\":\"7ce322e04b934a2087ffea6829e51b24.png\"},\"success\":true}",
    "header": "{\"dgtlEnvlp\":\"04388F2B1FB17953F0C5FEE5C26FBCAA1F74736F6C7FDF925F5FF0E9DBE47D23E00EBC9D715B15C617E1E7C436BBCE597289B714462A61760A7B6B488FB20F29B94B966C15A456EA884320BFBBFA3EB061E4DD4475331A56831F14A7FE5E0DF783E5F4B8802A09FD8D14D7B3674E01ECBE\",\"ncrptnSN\":\"1387287849\",\"parentUid\":\"13030918\",\"serviceTp\":\"T-1001-035-02\",\"signSN\":\"4026178988\",\"sysRespCode\":\"S_0000\",\"sysRespDesc\":\"请求正常\",\"verifyType\":\"10\"}",
    "sign": "304402204873EC33314A6E5371B2FADCC000F1C3FBF6F701103181CBD8D10A2720BC399D02201195086418EF4EC8946C2F880ECAA6661AE8AD76BA375AC302F9ACF3E27F172E"
}

header部分

序号 域名 变量名 必填 备注
01 商户号 parentUid R 宝付提供给商户的唯一编号
02 服务编号 serviceTp R 服务编号
03 签名证书序列号 signSN M 宝付的签名证书序列号
04 加密证书序列号 ncrptnSN M 商户的加密证书序列号
05 加密方式 verifyType R 10(SM2),11(RSA)
06 数字信封 dgtlEnvlp M 16位密钥,使用商户私钥解密获得明文
07 加密参数名 encryptParams O 若字段有值，则需要按照此字段描述解密业务报文
场景1: 值为$时,使用数字信封明文16位key对全报文解密
场景2: 值为字段名(逗号分隔)时,使用数字信封明文16位key对各个字段解密
例如传a,b,c 需要对报文body部分的a,b,c3个字段进行解密。
此字段需要Base64解码
08 系统返回码 sysRespCode M 见附录
09 系统返回信息 sysRespDesc M

body部分
参考具体业务接口的返回报文参数

响应报文示例
(示例部分未提供具体内容)

3. 异步通知说明

3.1 通知加密

verifyType值 签名方式
10 (国密) 1. 全报文(dataContent)用商户公钥SM2加密
2. 加密后的报文(dataContent)用宝付私钥进行SM2签名
3. 加密结果转成16进制
11 (RSA) 1. 全报文(dataContent)用商户公钥RSA(SHA256withRSA)加密
2. 加密后的报文(dataContent)用宝付私钥进行RSA签名
3. 加密结果转成16进制

3.1.1 RSA 证书长度与加解密数据长度说明

由于 RSA 算法本身的限制，单次加密与解密所支持的数据长度与证书位数直接相关，商户在实现加解密逻辑时需特别注意。

RSA 证书长度 最大加密数据长度 解密数据长度
1024 位 最大支持 117 字节 128 字节
2048 位 最大支持 245 字节 256 字节

说明：

  • RSA 加密时，实际可加密的数据长度需要扣除填充（Padding）所占用的字节空间
  • 当业务报文长度超过单次 RSA 加密上限时，需对原始数据进行分段加密处理
  • 解密时，每段密文长度固定等于证书位数所对应的字节长度
  • 建议商户在开发过程中统一封装 RSA 分段加解密工具方法，避免因长度限制导致加解密失败

3.2 通知频率

如果上传了异步通知地址，当成功或失败时候会收到宝付的异步通知。
异步通知以GET和POST方式发送到商户配置的接收地址，商户接收到支付结果，并且进行相应处理之后，需要商户接收通知的地址在页面上输出 OK 表示接收成功 除了 OK 无任何其他内容，告诉宝付已经成功接收并处理完毕，宝付系统在未得到商户接收通知成功的反馈时，将通过重发机制再次通知商户（重发次数 2~10 次，请以第一次收到的成功的消息为准，避免进行多次业务处理），直到商户接收成功或达到最大重发次数为止。

通知频率：0，2，5，10，30，60，90，180，240，820 单位是分钟

3.3 通知报文编号

参数名 说明
parentUid 代理商会员号
uid 交易会员号
charset 字符集 固定UTF-8
dataContent 密文
notifyType 通知类型 查看各通知文档
format 固定json
ncrptnSn 商户加密证书序列号
signSn 宝付签名证书序列号
verifyType 10 国密 11 RSA
signStr 签名串
version 固定1.0

3.4 报文编号

报文规则
采用”T-XXXX-YYY-NN”定义报文编号

  • T位固定位
  • XXXX 用来区分不同业务的报文
  • YYY 为预留位
  • NN 为报文版本号信息
取值 交易子类
BJR1-1004-001-01 成员授信结果查询
BJR1-1005-001-01 获取登录会话链接
BJR1-2004-001-01 融资结果查询
BJR1-8001-001-01 协议签署查询
BJR1-7001-001-01 企业电子信息分页查询

示例:
http://xxxx?parentUid=1300033460&uid=1300033460&charset=UTF-8&dataContent=A516259E715C9C5EE243919FAAA9CB12EBA5973C458D9F46AE28425764B3CAC1F5BFF8AF309F2DA26F253DF71A6004DFFD864BAB46BA7291B7581C07FF4C920D7F0E01B735A792167DE2FFD74F54184F773CADFE774B293CC2F8248B4A21A56792F4DCDFB6A41359044B7E0A73534D0F934B6C4483897CC4C6AE2CE4E7C4D99D12782F07F18C7E1E86429047E5D53345C7A768610BF5B193A9F99A457C3B2170A56E4C70B2739EB3BC920907CF85772B2E877DE5661067E9A2CF02A79AB2446B05D057EABEA5E1675FB4C08F4DEEDD132B7E01C35C59556F67CD3B19F826EB5E938F125E8D15512798274A68CAE522F7D50A26C9982E8AA909D079AEE389345A&notifyType=payment&format=json&ncrptnSn=1139986924&signStr=4FF5757C611546D35EBD3E39A1CA339CFEF8FC69796E8856E7193670E5EA6AD4D11F5A4FF541531D4FB97614D42CCD21E1C6217A0EF9103CB5A397AC1CDF586CDC4576CD2A60CF315612A4268257683A40EEDA6512CBA4B46F42454F256483BC2921BD0D9169FA115D32C4E72CFC5E28544108B0A5FC484E746A3FEDC955C0E5B9E3D4CD62751207DE9924947F9834C13EE872FD116350A5767D1DEF182B8842BFBC69D7D84D31C92548A07B2E8F27629DFC08B5EB619878FC160DA1ACD617705C9E3ADB08DEEB9E93C9D2057B8A1BB03F60D3CAEDFDF0E134D18A7BB9EE4E8A76DFDE64329418B19E721DE72D86897D7156E14E366E6CD3FB1253957B6C62D9&version=1.0&signSn=1139986924&verifyType=11

3.4 通知类型notifyType

notifyType 通知类型
BJR1-2101-001-01 放款结果通知
BJR1-1101-001-01 成员授信结果通知
BNK1-1103-001-01 电子户开户通知
BJR1-8101-001-01 协议签署通知

附录：

1. 系统响应码

注意：

  • 此响应码仅代表系统请求的一个到达情况，不作为业务处理的结果标识。
  • 具体业务处理响应，需要根据body中具体的相关状态标识判断。
错误码 含义 请求状态
S_0000 请求正常 正常(请查看body中的相关信息)
S_E_0001 明文参数格式不正确,%s 失败
S_E_0002 明文参数解析失败,%s 失败
S_E_0003 商户信息不存在或状态不正常 失败
S_E_0004 商户与终端号不匹配 失败
S_E_0005 ip未绑定，请联系宝付 失败
S_E_0006 密文解密失败 失败
S_E_0007 密文参数解析失败 失败
S_E_0008 头参数格式不正确,%s 失败
S_E_0009 头参数和文明参数不一致,%s 失败
S_E_0010 接口服务报文不支持 失败
S_E_0011 验签失败 失败
S_E_0012 解密失败 失败
S_E_0013 签名失败 未知
S_E_0014 数字信封解密失败 失败
S_E_0015 证书已过期 失败
S_E_9001 请求受理失败 失败
S_E_9002 请求受理结果未知 未知
S_E_0013 生成数字信封失败 未知

2. 报文编号

报文规则
采用”TTTT-XXXX-YYY-NN”定义报文编号

  • TTTT位固定位
  • XXXX 用来区分不同业务的报文
  • YYY 为预留位
  • NN 为报文版本号信息
作者：xiaochen  创建时间：2025-12-18 20:28
最后编辑：卓琳赫  更新时间：2026-02-02 14:28