1 文档说明
1.1 文档目的
本文档是为宝付协议支付API产品定义一个接口规范,以帮助商户技术人员快速接入宝付协议支付API网关,并快速掌握其相关功能,便于尽快的投入使用。
1.2 阅读对象
- 商户开发人员、维护人员和管理人员
- 宝付协议支付API产品相关的技术人员
1.3 技术支持
在开发或使用宝付协议支付API接口时,如果您有任何技术上的疑问,请按如下方式寻求帮助,宝付技术支持人员会及时处理,给予您答复:
技术支持热线:021-68819999-8005
技术支持Email:support@baofoo.com
技术支持QQ:800066689
1.4 术语与定义
1.4.1 符号含义
序号 | 符号缩写 | 符号性质 | 符号说明 |
---|---|---|---|
1 | M | 强制域(Mandatory) | 必须填写的属性,否则会被认为格式错误 |
2 | C | 条件域(Conditional) | 某条件成立时必须填写的属性 |
3 | O | 选用域(Optional) | 选填属性 |
4 | R | 原样返回域(Returned) | 必须与先前报文中对应域的值相同的域 |
数据类型
类型语法:[Max][Min][Size][Type]
Max:可选描述符,如果出现,则说明业务要素的长度最大为Size
Min:可选描述符,如果出现,则说明业务要素的长度最小为Size
Size:强制描述符,指定业务要素UTF-8编码前的最大字符数。
Type:强制描述符,指定业务要素的类型属性。Type主要属性如下
序号 | 字段类型Type | 符号说明 |
---|---|---|
1 | code | 编码枚举型数据,具体枚举类型见附录:枚举类型 |
2 | Text | 字符串 |
3 | Numeric | 数字 |
4 | ISODateTime | 日期时间,格式为 yyyy-MM-dd HH:mm:ss ,如:2017-12-20 21:54:21 |
字符集及编码
报文采用Unicode字符集,UTF-8编码方式。
保留字
报文内容中“|”、“%”、 “#”、 “^”、 “-”等为局部保留字,在相关以此类字符作为分隔符的复合字段中不应出现。
1.4.2 术语含义
- 商户号:宝付提供给商户的唯一编号,是商户在宝付的唯一标识;
- 终端号:商户在与宝付签订某项具体产品功能的合作协议自动分配的会员属性,将用于进行具体交易的必要参数。
- 商户流水号:商户请求宝付时提交的流水号,每次请求均不可重复;
1.5 通讯模式
采用HTTPS方式进行通讯。
1.6 报文说明
1.6.1 请求报文
请求报文格式
格式:key1=value1&key2=value2&key3=value3…
例如:send_time=2018-01-24 13:25:33&msg_id=456795112&version=4.0.0.0&terminal_id=100000949&txn_type=03&member_id=100000749&dgtl_envlp=5a9c3ac419735d249e319727c89cfc0ce4a80d6a954980eaf3ea934316a56a121c758b0d13bf3302b877a8dd68619db72b2bd588ccdc9eb7fdb455705be1909df96540009146d7d81c96c0b90578f9344bd3fc00ded94d27c0c8040a83c02114b7a3a4698f830b7d0db60f230a5c3a4b38e7104088f2ee0139a4e765a9d79255&user_id=123&signature=7ca60bdea1f253b1a09588f7e4f0d455d984eaad0a446e61044c1527ea19fbdd70d690cc627327955b7a01a58acbc11cad6a26f8086c1bf23126da36832be59c46bc20e942bcae7614fcd9ba4dc7eec4c5e17024fb04fe5e63f2d137a3517a1e0c7bdea6d4ae33dbab7d20543e474a4bd790f7ba42cacaef45730623482a70ac
将除签名字段之外的不为空的字段按key-value的形式构建TreeMap<String, String>对象,按key1=value1&key2=value2…模式将TreeMap对象转换为字符串,UTF-8编码格式下进行SHA-1计算后转换为16进制字节数组,用商户RSA私钥签名后转16进制。
生成AES密钥,按照如下拼装:
格式:01|对称密钥
,01代表AES算法
加密方式:Base64转码后使用宝付的公钥RSA加密
加密方式:Base64转码后,使用数字信封指定的方式和密钥加密
1.6.2 返回报文
返回报文格式
格式:key1=value1&key2=value2&key3=value3…
例如:
biz_resp_code=0000&biz_resp_msg=交易成功&dgtl_envlp=74652829c07a71983c0da582321818aec41364528626e0f90eac1c633755b9dab84593695f5a101401052e9c64d457a881e442206330215de2281d2a3ea15d79e6732e296fdc36c6e0c76d17376cf6b9fc978b50bc747a9536d93226a69aba587f9fa5227a9b2cb915d1b822753f4a86a9fa1d81bf4d106723d927cf0f6365fb&member_id=100000749&msg_id=4a3f0b1862b94b6f853c1d28f9913f82&protocols=f222d7fe76b7c8ea7e22f3ee315e579a4263d697b12de605c287018e15cd530358dd8f638e4211b09e4e250d6b352304e0b454332aa0efda6977d435cf911dbc3943615ae31752e9a87c6e4b69dfc9e3af6be7a9a6e3f6a92a63e65b59936beb&resp_code=S&send_time=2018-01-25 09:53:01&signature=8ab74c7869632dc395cc945adcc388e6afceb759e4d406c3bb6e0e8002ec422f1615f2a43966d7337dcc57963f18877a959fe9f67b082da2cd95217ba003cc81f07962d665f576509ebc1a38f7ddf2a423775a794b262b7ffc4af615da3ba6bd05d0672c004d7cf80be3ed236f268078bb5c700d4b0a6ae9a0e58f2c782bd6ef&terminal_id=100000949&txn_type=03&version=4.0.0.0
将宝付返回的除签名字段之外的不为空的字段按key-value的形式构建TreeMap<String, String>对象,按key1=value1&key2=value2…模式将TreeMap对象转换为字符串,UTF-8编码格式下进行SHA-1计算后转换为16进制字节数组。将宝付返回的签名字段转16进制字节数组,用宝付RSA公钥验签。
解密方式:后使用商户的私钥解密后Base64解码
解密后格式:01|对称密钥
,01代表AES算法
解密方式:使用数字信封指定的方式和密钥解密后Base64解码
2、业务接口说明
2.1应用场景
在用户明确授权基础上,允许商户及我司在用户规定的多张银行卡间灵活扣款。保障还款顺畅支付,提升还款成功率,降低逾期风险。
使用此接口前用户必须先有签约协议号,此协议号通过调用我司绑卡接口获取。
2.2业务接口
2.2.1获取多签约支付协议
交易URL
测试环境地址:https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
正式环境地址:https://public.baofoo.com/cutpayment/protocol/backTransRequest
请求报文
序号 | 域名 | 变量名 | 必填 | 字段类型 | 备注 |
---|---|---|---|---|---|
1. | 报文发送日期时间 | send_time | M | ISODateTime | 发送方发出本报文时的机器日期时间,如 2017-12-19 20:19:19 |
2. | 报文流水号 | msg_id | M | Max32Text | 商户流水号 |
3. | 报文编号/版本号 | version | M | Max7Text | 4.0.0.0 |
4. | 终端号 | terminal_id | M | Max11Numeric | |
5. | 交易类型 | txn_type | M | code | 161 |
6. | 商户号 | member_id | M | Max11Numeric | 宝付提供给商户的唯一编号 |
7. | 数字信封 | dgtl_envlp | M | Max512Text | 格式:01|对称密钥,01代表AES 加密方式:Base64转码后使用宝付的公钥加密 |
8. | 签约协议号 | protocol_no | M | Max126Text | 加密方式:Base64转码后,使用数字信封指定的方式和密钥加密 |
9. | 商户保留域1 | req_reserved1 | O | Max255Text | |
10. | 商户保留域2 | req_reserved2 | O | Max255Text | |
11. | 系统保留域1 | additional_info1 | O | Max255Text | |
12. | 系统保留域2 | additional_info2 | O | Max255Text | |
13. | 签名域 | signature | M | Max512Text |
返回报文
序号 | 域名 | 变量名 | 必填 | 字段类型 | 备注 |
---|---|---|---|---|---|
1 | 报文发送日期时间 | send_time | M | ISODateTime | 发送方发出本报文时的机器日期时间,如:2017-12-19 20:19:19 |
2 | 应答报文流水号 | msg_id | M | Max32Text | |
3 | 报文编号/版本号 | version | R | Max7Text | 4.0.0.0 |
4 | 应答码 | resp_code | M | 具体参见附录5:商户接口应答码 | |
5 | 终端号 | terminal_id | R | Max11Numeric | |
6 | 交易类型 | txn_type | R | code | |
7 | 商户号 | member_id | R | Max11Numeric | 宝付提供给商户的唯一编号 |
8 | 业务返回码 | biz_resp_code | M | 具体参见附录1:业务应答码 | |
9 | 业务返回说明 | biz_resp_msg | M | ||
10 | 授权信息 | auth | C | Max512Text | 格式:授权码|协议链接 加密方式:Base64转码后,使用数字信封指定的方式和密钥加密 协议链接及授权码有效期30分钟 |
11 | 数字信封 | dgtl_envlp | M | Max512Text | 格式:01|对称密钥,01代表AES 加密方式:Base64转码后使用商户的公钥加密 |
12 | 商户保留域1 | req_reserved1 | O | Max255Text | |
13 | 商户保留域2 | req_reserved2 | O | Max255Text | |
14 | 系统保留域1 | additional_info1 | O | Max255Text | |
15 | 系统保留域2 | additional_info2 | O | Max255Text | |
16 | 签名域 | signature | M | Max512Text |
2.2.2多签约支付授权
交易URL
测试环境地址:https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
正式环境地址:https://public.baofoo.com/cutpayment/protocol/backTransRequest
请求报文
序号 | 域名 | 变量名 | 必填 | 字段类型 | 备注 |
---|---|---|---|---|---|
1 | 报文发送日期时间 | send_time | M | ISODateTime | 发送方发出本报文时的机器日期时间,如 2017-12-19 20:19:19 |
2 | 报文流水号 | msg_id | M | Max32Text | 商户流水号 |
3 | 报文编号/版本号 | version | M | Max7Text | 4.0.0.0 |
4 | 终端号 | terminal_id | M | Max11Numeric | |
5 | 交易类型 | txn_type | M | code | 162 |
6 | 商户号 | member_id | M | Max11Numeric | 宝付提供给商户的唯一编号 |
7 | 数字信封 | dgtl_envlp | M | Max512Text | 格式:01|对称密钥,01代表AES 加密方式:Base64转码后使用宝付的公钥加密 |
9 | 授权码 | auth_code | M | Max126Text | 加密方式:Base64转码后,使用数字信封指定的方式和密钥加密 |
10 | 商户保留域1 | req_reserved1 | O | Max255Text | |
11 | 商户保留域2 | req_reserved2 | O | Max255Text | |
12 | 系统保留域1 | additional_info1 | O | Max255Text | |
13 | 系统保留域2 | additional_info2 | O | Max255Text | |
14 | 签名域 | signature | M | Max512Text |
返回报文
序号 | 域名 | 变量名 | 必填 | 字段类型 | 备注 |
---|---|---|---|---|---|
1 | 报文发送日期时间 | send_time | M | ISODateTime | 发送方发出本报文时的机器日期时间,如 2017-12-19 20:19:19 |
2 | 应答报文流水号 | msg_id | M | Max32Text | |
3 | 报文编号/版本号 | version | R | Max7Text | 4.0.0.0 |
4 | 应答码 | resp_code | M | Max16Text | 具体参见附录5:商户接口应答码 |
5 | 终端号 | terminal_id | R | Max11Numeric | |
6 | 交易类型 | txn_type | R | code | |
7 | 商户号 | member_id | R | Max11Numeric | 宝付提供给商户的唯一编号 |
8 | 业务返回码 | biz_resp_code | M | 具体参见附录1:业务应答码 | |
9 | 业务返回说明 | biz_resp_msg | M | ||
14 | 商户保留域1 | req_reserved1 | O | Max255Text | |
15 | 商户保留域2 | req_reserved2 | O | Max255Text | |
16 | 系统保留域1 | additional_info1 | O | Max255Text | |
17 | 系统保留域2 | additional_info2 | O | Max255Text | |
18 | 签名域 | signature | M | Max512Text |
2.2.3多签约解约
交易URL
测试环境地址:https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
正式环境地址:https://public.baofoo.com/cutpayment/protocol/backTransRequest
请求报文
序号 | 域名 | 变量名 | 必填 | 字段类型 | 备注 |
---|---|---|---|---|---|
1. | 报文发送日期时间 | send_time | M | ISODateTime | 发送方发出本报文时的机器日期时间,如 2017-12-19 20:19:19 |
2. | 报文流水号 | msg_id | M | Max32Text | 商户流水号 |
3. | 报文编号/版本号 | version | M | Max7Text | 4.0.0.0 |
4. | 终端号 | terminal_id | M | Max11Numeric | |
5. | 交易类型 | txn_type | M | code | 167 |
6. | 商户号 | member_id | M | Max11Numeric | 宝付提供给商户的唯一编号 |
7. | 签约协议号 | protocol_no | M | Max126Text | 加密方式:Base64转码后,使用数字信封指定的方式和密钥加密 |
8. | 数字信封 | dgtl_envlp | M | Max512Text | 格式:01|对称密钥,01代表AES 加密方式:Base64转码后使用宝付的公钥加密 |
9. | 商户保留域1 | req_reserved1 | O | Max255Text | |
10. | 商户保留域2 | req_reserved2 | O | Max255Text | |
11. | 系统保留域1 | additional_info1 | O | Max255Text | |
12. | 系统保留域2 | additional_info2 | O | Max255Text | |
13. | 签名域 | signature | M | Max512Text |
返回报文
序号 | 域名 | 变量名 | 必填 | 字段类型 | 备注 |
---|---|---|---|---|---|
1. | 报文发送日期时间 | send_time | M | ISODateTime | 发送方发出本报文时的机器日期时间,如 2017-12-19 20:19:19 |
2. | 应答报文流水号 | msg_id | M | Max32Text | |
3. | 报文编号/版本号 | version | M | Max7Text | 4.0.0.0 |
4. | 应答码 | resp_code | M | Max16Text | 具体参见附录5:商户接口应答码 |
5. | 终端号 | terminal_id | R | Max11Numeric | |
6. | 交易类型 | txn_type | R | Max11Text | |
7. | 商户号 | member_id | R | Max11Numeric | 宝付提供给商户的唯一编号 |
8. | 业务返回码 | biz_resp_code | M | 具体参见附录1:业务应答码 | |
9. | 业务返回说明 | biz_resp_msg | M | ||
10. | 商户保留域1 | req_reserved1 | O | Max255Text | |
11. | 商户保留域2 | req_reserved2 | O | Max255Text | |
12. | 系统保留域1 | additional_info1 | O | Max255Text | |
13. | 系统保留域2 | additional_info2 | O | Max255Text | |
14. | 签名域 | signature | M | Max512Text |
2.2.4多签约支付授权结果查询
交易URL
测试环境地址:https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
正式环境地址:https://public.baofoo.com/cutpayment/protocol/backTransRequest
请求报文
序号 | 域名 | 变量名 | 必填 | 字段类型 | 备注 |
---|---|---|---|---|---|
1. | 报文发送日期时间 | send_time | M | ISODateTime | 发送方发出本报文时的机器日期时间,如 2017-12-19 20:19:19 |
2. | 报文流水号 | msg_id | M | Max32Text | 商户流水号 |
3. | 报文编号/版本号 | version | M | Max7Text | 4.0.0.0 |
4. | 终端号 | terminal_id | M | Max11Numeric | |
5. | 交易类型 | txn_type | M | code | 163 |
6. | 商户号 | member_id | M | Max11Numeric | 宝付提供给商户的唯一编号 |
7. | 签约协议号 | protocol_no | M | Max126Text | 加密方式:Base64转码后,使用数字信封指定的方式和密钥加密 |
8. | 数字信封 | dgtl_envlp | M | Max512Text | 格式:01|对称密钥,01代表AES 加密方式:Base64转码后使用宝付的公钥加密 |
9. | 商户保留域1 | req_reserved1 | O | Max255Text | |
10. | 商户保留域2 | req_reserved2 | O | Max255Text | |
11. | 系统保留域1 | additional_info1 | O | Max255Text | |
12. | 系统保留域2 | additional_info2 | O | Max255Text | |
13. | 签名域 | signature | M | Max512Text |
返回报文
序号 | 域名 | 变量名 | 必填 | 字段类型 | 备注 |
---|---|---|---|---|---|
1. | 报文发送日期时间 | send_time | M | ISODateTime | 发送方发出本报文时的机器日期时间,如 2017-12-19 20:19:19 |
2. | 应答报文流水号 | msg_id | M | Max32Text | |
3. | 报文编号/版本号 | version | M | Max7Text | 4.0.0.0 |
4. | 应答码 | resp_code | M | Max16Text | 具体参见附录5:商户接口应答码 |
5. | 终端号 | terminal_id | R | Max11Numeric | |
6. | 交易类型 | txn_type | R | Max11Text | |
7. | 商户号 | member_id | R | Max11Numeric | 宝付提供给商户的唯一编号 |
8. | 业务返回码 | biz_resp_code | M | 具体参见附录1:业务应答码 | |
9. | 业务返回说明 | biz_resp_msg | M | ||
15. | 商户保留域1 | req_reserved1 | O | Max255Text | |
16. | 商户保留域2 | req_reserved2 | O | Max255Text | |
17. | 系统保留域1 | additional_info1 | O | Max255Text | |
18. | 系统保留域2 | additional_info2 | O | Max255Text | |
19. | 签名域 | signature | M | Max512Text |
3、业务应答码
错误码 | 含义 |
---|---|
0000 | 交易成功 |
BF00436 | 交易类型不存在 |
BF00121 | 报文交易要素格式错误 |
BF00123 | 商户不存在或状态不正常,请联系宝付 |
BF00116 | 该终端号不存在 |
BF00124 | 商户与终端号不匹配 |
BF00316 | ip未绑定,请联系宝付 |
BF00313 | 该商户未开通此产品 |
BF00100 | 系统异常,请联系宝付 |
BF00450 | 签名验证失败 |
BF00437 | 不支持的密钥类型 |
BF00118 | 报文中密文解析失败 |
BF00331 | 卡号校验失败 |
BF00438 | 不支持的卡类型 |
BF00322 | 卡类型和卡号不匹配 |
BF00190 | 商户流水号不能重复 |
BF00101 | 持卡人信息有误 |
BF00111 | 交易失败 |
BF00112 | 系统繁忙,请稍后再试 |
BF00113 | 交易处理中,请稍后查询 |
BF00249 | 订单已过期,请使用新的订单号发起交易 |
BF00105 | 短信验证码错误 |
BF00106 | 短信验证码失效 |
BF00258 | 手机号码校验失败 |
BF00261 | 短信验证码错误次数超限,请重新获取 |
BF00260 | 短信验证码已过期,请重新发送 |
BF00107 | 当前银行卡不支持该业务,请联系发卡行 |
BF00108 | 交易失败,请联系发卡行 |
BF00140 | 该卡已被注销 |
BF00141 | 该卡已挂失 |
BF00237 | 该卡已冻结,请联系发卡行 |
BF00236 | 卡号无效,请确认后输入 |
BF00327 | 请联系银行核实您的卡状态是否正常 |
BF00332 | 交易失败,请重新支付 |
BF00343 | 验证失败(手机号有误) |
BF00346 | 验证失败(身份证号有误) |
BF00347 | 交易次数频繁,请稍后重试 |
BF00355 | 验证失败(卡状态异常) |
BF00202 | 交易超时,请稍后查询 |
BF00135 | 交易金额不正确 |
BF00134 | 绑定关系不存在 |
BF00127 | 不支持该支付通道的交易 |
BF00114 | 订单已支付成功,请勿重复支付 |
BF00249 | 订单已过期,请使用新的订单号发起交易 |
BF00126 | 该笔订单已存在 |
BF00136 | 订单创建失败 |
BF00342 | 单卡单日余额不足次数超限 |
BF08704 | 单笔金额超限,该银行单笔可支付{}元! |
BF00325 | 目前该银行正在维护中,请更换其他银行卡支付 |
BF08703 | 支付金额需大于最低限额{}元! |
BF00234 | 单日交易金额超限! |
BF00255 | 发送短信验证码失败 |
BF00128 | 该笔订单不存在 |
BF00262 | 交易金额与扣款成功金额不一致,请联系宝付 |
BF00103 | 账户余额不足 |
BF00104 | 交易金额超限 |
BF00235 | 单笔交易金额超限 |
BF00421 | 持卡人已与银行解绑,请重新绑卡后再进行支付! |
BF00422 | 该用户信息发生变更,请重新绑卡 |
BF00334 | 分账信息格式不正确 |
BF00335 | 分账参数验证失败 |
BF00336 | 分账信息和之前不一致 |
BF00337 | 分账指令已经受理 |
BF00338 | 分账成功 |
BF00339 | 已分账 |
BF00423 | 绑卡失败,请重新签约 |
BF00376 | 该笔交易,扣款已成功,待分账 |
BF00110 | 该卡暂不支持此交易 |
BF00468 | 该母订单已确认,请勿重复确认 |
BF00469 | 母订单状态非待确认状态 |
BF00470 | 订单待确认 |
BF00480 | 订单超时失败 |
BF00504 | 已解约 |
4、交易类型枚举
交易类型 | 交易描述 |
---|---|
161 | 查询多签约支付协议 |
162 | 多签约支付授权 |
163 | 多签约支付授权结果查询 |
167 | 多签约解约 |
5、商户接口应答码
应答码 | 含义 |
---|---|
S | 成功 |
F | 失败 |
I | 处理中 |
FF | 失败(支付结果查询类交易才会返回,表示订单查询参数错误或其他原因导致的订单查询失败,而非订单交易失败) |
最后编辑:xiaofeng 更新时间:2024-09-19 18:06