1. 文档说明

1.1 文档目的

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

1.2 阅读对象

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

1.3 技术支持

在开发或使用接口文档时，如果您有任何技术上的疑问，请按如下方式寻求帮助，宝付技术支持人员会及时处理，给予您答复：

  • 技术支持热线：021-68819999
  • 技术支持Email：support@baofu.com
  • 技术支持QQ：800066689

1.4 术语与定义

1.4.1 符号含义

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

1.4.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位密钥
09 加密参数名 encryptParams O 如有字段需要加密,则必传,服务端会按照此字段解密业务报文
场景1: 需要加密全报文,传$,服务端会全报文解密
场景2: 部分字段加密,传字段名,用逗号分隔
例如传a,b,c 那么服务端会对报文body部分的a,b,c3个字段进行解密。
此字段需要转成字节后用Base64.encodeBase64URLSafeString的方式进行加密后传输
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 应答的加密参数名,规则参考请求参数
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.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

示例:
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

附录：

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 为报文版本号信息
作者：庞寅  创建时间：2025-05-15 14:11
最后编辑：庞寅  更新时间：2025-05-15 21:25