使用授权声明
本文档中所包含的信息属于商业机密信息，应严格控制使用范围，如无宝付网络科技（上海）有限公司（以下简称“宝付”）的书面许可，任何人员不得以任何介质方式持有或使用本文档的部分或全部内容。

文档修订记录

1 文档说明

1.1 文档目的

本文档旨在为宝付批量协议支付API产品定义接口规范，帮助商户技术人员快速接入宝付批量协议支付网关，掌握相关功能并尽快投入使用。

1.2 阅读对象

• 商户开发人员、维护人员和管理人员
• 宝付协议支付API产品相关的技术人员

1.3 技术支持

在开发或使用宝付协议支付API接口时，如果您有任何技术上的疑问，请按如下方式寻求帮助，宝付技术支持人员会及时处理，给予您答复：
技术支持热线：021-68819999-8005
技术支持Email：support@baofoo.com
技术支持QQ：800066689

1.4 术语与定义

1.4.1 符号含义

数据类型

类型语法：[Max][Min][Size][Type]
Max:可选描述符，如果出现，则说明业务要素的长度最大为Size
Min:可选描述符，如果出现，则说明业务要素的长度最小为Size
Size：强制描述符，指定业务要素UTF-8编码前的最大字符数。
Type：强制描述符，指定业务要素的类型属性。Type主要属性如下

字符集及编码

报文采用Unicode字符集，UTF-8编码方式。

保留字

报文内容中“|”、“%”、 “#”、 “^”、 “-”等为局部保留字，在相关以此类字符作为分隔符的复合字段中不应出现。

1.4.2 术语含义

• 商户号：宝付提供给商户的唯一编号，是商户在宝付的唯一标识。
• 终端号：商户在与宝付签订某项具体产品功能的合作协议自动分配的会员属性，将用于进行具体交易的必要参数。
• 商户流水号：商户请求宝付时提交的流水号，每次请求均不可重复。
• 商户订单号：商户请求宝付时提交的订单号，当天请求不可重复，如果商户开通“发送短信类交易”，该订单号从发送短信类交易到当前交易都有效。
• 宝付交易号：宝付用于一笔订单的唯一标识。

1.5 通讯模式

采用HTTPS方式进行通讯。

2 业务接口说明

2.1 应用场景

商户分批次通过接口传递扣款请求，宝付实时回复收到请求响应；后端发各银行扣款后，再异步通知商户每一条订单的结果（成功或失败）；同时，商户可以来查询每笔订单或某批次的订单。
注：该接口为后台指令模式

目前银行要求在商户平台页面上挂持卡人与银行之间的服务协议（快捷支付、协议支付），用户在绑卡时需要用户详细阅读并同意协议，才可以提供协议支付服务。各家银行的协议内容不一样，已经放到接口包里。如果不清楚可联系技术支持。银行挂网协议材料点击下载

2.2 绑卡业务流程

商户在使用宝付批量非实时协议支付分账产品进行扣款前，所有用户都需要提前绑卡，获取协议ID后才能进行扣款流程；扣款流程中，商户可以选传用户的协议ID或四要素信息进行扣款。
注：绑卡相关业务，包括预绑卡、确认绑卡、解除银行卡绑定和绑定关系查询接口，请求报文格式和签名算法参照如下说明：

2.2.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转码后，使用数字信封指定的方式和密钥加密

2.2.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.3 扣款业务流程

2.3.1 扣款业务流程

1. 商户将批量协议支付订单发送至宝付，单笔明细采用分隔符#连接交易要素，最大支持5000笔明细；
2. 宝付做商户接入校验，IP、模板等后，同步返回受理成功响应给商户；
3. 宝付异步并发处理交易明细，支付要素验证成功后，向银行发扣款请求；
4. 银行/银联将交易处理完成并通知宝付交易结果；
5. 宝付将交易结果(成功或失败)异步发送给商户。

2.3.2 密文传输流程图

2.4 业务接口

2.4.1 预绑卡

绑定银行卡是指经过持卡人授权将个人银行卡和商户建立绑定关系，支付时不再需要输入银行卡信息。商户需先进行预绑卡，银行会发送短信验证码给持卡人，商户再使用确认绑卡接口将短信验证码回传给宝付完成绑卡。

交易URL

• 测试环境地址：https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
• 正式环境地址：https://public.baofoo.com/cutpayment/protocol/backTransRequest

请求报文

返回报文

2.4.2 确认绑卡

绑定银行卡是指经过持卡人授权将个人银行卡和商户建立绑定关系，支付时不再需要输入银行卡信息。商户需先进行预绑卡，银行会发送短信验证码给持卡人，商户再使用确认绑卡接口将短信验证码回传给宝付完成绑卡。

交易URL

• 测试环境地址：https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
• 正式环境地址：https://public.baofoo.com/cutpayment/protocol/backTransRequest

请求报文

返回报文

2.4.3 解除银行卡绑定

解绑是指持卡人发起的银行卡和商户解除绑定关系的业务。

交易URL

• 测试环境地址：https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
• 正式环境地址：https://public.baofoo.com/cutpayment/protocol/backTransRequest

请求报文

返回报文

2.4.4 绑定结果查询

交易URL

• 测试环境地址：https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
• 正式环境地址：https://public.baofoo.com/cutpayment/protocol/backTransRequest

请求报文

返回报文

2.4.5 批量协议支付

批量协议支付交易是指商户通过批量接口传递多笔协议支付明细，宝付实时回复收到请求响应受理；后端发各银行进行扣款，银行反馈宝付扣款结果后，宝付再异步通知商户每一条订单的结果（成功或失败），该模式属于后台支付模式。

交易URL

• 测试环境地址：https://vgw.baofoo.com/batchpay/api/batchTransRequest
• 正式环境地址：https://public.baofoo.com/batchpay/api/batchTransRequest

请求报文

加密数据data_content

实际信息说明：actual_info为实际信息集合，子节点为info，最多支持5000个子节点，info内具体内容采用分隔符”#”分割模式，请注意分割字段内容中不要在出现分隔符导致混淆。
字段分割顺序如下:
trans_id#trans_date#acc_no#id_holder#id_card_type#id_card#mobile#txn_amt#req_reserved#protocol_no
各字段具体介绍如下

加密数据模板:

XML

<?xml version="1.0" encoding="UTF-8" ?>
<data_content>
    <terminal_id>10001</terminal_id>
    <member_id>100000362</member_id>
    <txn_sub_type >32</ txn_sub_type >
<trans_serial_no>32132132130001</trans_serial_no>
< trans_batch_id>32132132130001</ trans_batch_id>
<actual_info >
    <info>TX0001#20160719111111#6226**943#张三#01#320382**1122#185**222#1#保留域</ info >
    <info>TX0001#20160719111111#6226**943#张三#01#320382**1122#185**222#1#保留域</ info >
    <info>TX0001#20160719111111#6226**943#张三#01#320382**1122#185**222#1#保留域</ info >
    <info>TX0001#20160719111111#6226**943#张三#01#320382**1122#185**222#1#保留域#1201805090933328080000002160</ info >
<actual_info >
</data_content>

JSON

    "data_content": {
     "terminal_id":"10001",
     "member_id":"100000362",
      "trans_serial_no":"32132132130001",
      "trans_batch_id ":"32132132130001",
      "actual_info":{
       "info":[
               "TX0001#20160719111111#6226**943#张三#01#320382**1122#185**222#1#保留域",
            "TX0001#20160719111111#6226**943#张三#01#320382**1122#185**222#1#保留域#1201805090933328080000002160"]
        }
    }

应答报文（宝付返回报文）

2.4.6 批量协议支付批次查询

商户可通过该接口向我司发起批量查询请求，查询该批次中每笔订单状态，根据返回的信息明确判断订单是否支付成功。

交易URL

• 测试环境地址：https://vgw.baofoo.com/batchpay/api/batchTransRequest
• 正式环境地址：https://public.baofoo.com/batchpay/api/batchTransRequest

请求报文

加密数据data_content

加密数据模板:

XML

<?xml version="1.0" encoding="UTF-8" ?>
<data_content>
    <txn_sub_type>19</txn_sub_type>
    <terminal_id>10001</terminal_id>
    <member_id>100000362</member_id>
    <trans_serial_no>1236546587654</trans_serial_no>
    <batch_id>32143434</ batch_id>
    <trans_batch_id>TX213213</trans_batch_id >
</data_content>

JSON

{
"txn_sub_type":"06",
"terminal_id":"10001",
"member_id":"100000362",
"trans_serial_no":"1236546587654",
"batch_id":"32143434",
"trans_batch_id":"TX213213"
}

应答报文（宝付返回报文）

支付响应结果由宝付通过非对称加密公私钥方式发送给商户。商户接收到宝付的响应报文，将接收到的内容，用宝付发给商户且后缀为（*.cer）的公钥证书进行解密。

应答结果解密后的报文格式是根据原交易订单请求的“data_type”来决定，输出内容包括

实际信息说明：actual_info为实际信息集合，子节点为info， 字段分割顺序如下:
trans_id#order_stat# resp_code# resp_msg# trans_no# succ_amt#req_reserved
各字段具体介绍如下

响应数据模板:

XML

<?xml version="1.0" encoding="utf-8"?>
<result>
  <resp_code>0000</resp_code>
  <resp_msg>查询成功</resp_msg>
  <member_id>100000749</member_id>
  <terminal_id>100000933</terminal_id>
  <actual_info>
    <info>20160724143920100#S#0000#交易成功#201607260110000600022065#1.00#</info>
    <info>20160724143920101#S#0000#交易成功#201607260110000600022066#1.00#</info>
    <info>20160724143920102#S#0000#交易成功#201607260110000600022067#1.00#</info>
  </actual_info>
</result>

JSON

{
 "actual_info": {
        "info": [
            "20160724143920100#S#0000#交易成功#201607260110000600022065#1.00#",
            "20160724143920101#S#0000#交易成功#201607260110000600022066#1.00#",
            "20160724143920102#S#0000#交易成功#201607260110000600022067#1.00#",
            "20160724143920103#S#0000#交易成功#201607260110000600022068#1.00#"
        ]
    },
    "member_id": "100000749",
    "resp_code": "0000",
    "resp_msg": "查询成功",
    "terminal_id": "100000933"
}

2.4.7 批量协议支付单笔查询

商户可通过该接口向我司发起查询请求，查询单笔订单的状态，宝付根据商户请求的原交易订单号返回该笔订单支付是否成功。如有重复发起交易的订单，以第一个成功交易为准，返回该订单相关信息。

交易URL

• 测试环境地址：https://vgw.baofoo.com/batchpay/api/batchTransRequest
• 正式环境地址：https://public.baofoo.com/batchpay/api/batchTransRequest

请求报文

加密数据data_content

加密数据模板:

XML

<?xml version="1.0" encoding="utf-8"?>
<data_content>
  <txn_sub_type>20</txn_sub_type>
  <terminal_id>100000933</terminal_id>
  <member_id>100000749</member_id>
  <trans_id>20160724143920108</trans_id>
  <trans_serial_no>20160727130342</trans_serial_no>
</data_content>

JSON

{
    "txn_sub_type": "20",
    "terminal_id": "100000933",
    "member_id": "100000749",
    "trans_serial_no": "20160727125614",
    "trans_id": "20160724143920108"
}

应答报文（宝付返回报文）

支付响应结果由宝付通过非对称加密公私钥方式发送给商户。商户接收到宝付的响应报文，将接收到的内容，用宝付发给商户且后缀为（*.cer）的公钥证书进行解密。

应答结果解密后的报文格式是根据原交易订单请求的“data_type”来决定，输出内容包括

实际信息说明：order_info为实际信息集合，具体结果参数如下：

响应数据模板:

XML

<?xml version="1.0" encoding="utf-8"?>
<result>
  < resp_code >0000</ resp_code >
  < resp_msg >查询成功</ resp_msg >
  <member_id>100000749</member_id>
  <terminal_id>100000933</terminal_id>
  <order_info>
      <trans_date>20160724143907</trans_date>
      <trans_id>20160724143920108</trans_id>
      <batch_id>2016072640195</ batch_id >
      <order_stat>S</order_stat>
      <resp_code>0000</resp_code>
      <resp_msg>交易成功</resp_msg>
      <trans_no>201607260110000600022073</trans_no>
      <succ_amt>1.00</succ_amt>
      <req_reserved>保留域</req_reserved>
      <trans_batch_id>123321323232</trans_batch_id>
</order_info>
</result>

JSON

{
    " resp_code ": "0000",
    " resp_msg": "查询成功",
    "member_id": "100000749",
    "terminal_id": "100000933",
    " order_info ": {
            "batch_id": "2016072640195",
            "order_stat": "S",
            "req_reserved": "",
            "resp_code": "0000",
            "resp_msg": "交易成功",
            "succ_amt": "1.00",
            "trans_date": "20160724143907",
            "trans_id": "20160724143920108",
            "trans_no": "201607260110000600022073",
            "trans_batch_id ": "4343433433222"
     }
}

2.4.8 异步通知

功能说明:
该接口商户接收通知的异步地址请联系对接讨论组宝付技术支持或商户经理协助进行配置，配置后方可使用。

通知报文

data_content=261a490a45070b3dd58ca5efa058b35973f39ebbdff5356d942a36cfe364726d7092a4305b22e758c3d95d66967bff9de548353adc265b906cebc0e942bf3f077e9f92344197d5a710ac925f43f8aa0c89df16b4fcef412ee5f56a36d8dfbdda39389146d0a6ae760acf94618e14b4f0bf37b77fbb3481c7739a7b421f3037ff90d5b1dadab1ed480683f02b9c5ad718f7602de55b8db0733c7632113c7b3635aeb1f06ab852567508f1b8ade380b071eeefdba4584c785aeb6f9f8b5c488b4ef8dbec978ef33d4ead8f4950d5d10186484842c73d064c49097b0d3e2dc13b891cace19c4766c7e73f0f6241090ec14cb273d1e655d895da21aafc159058765367dfa7983ba1c60a9f752032e25fab9324562c6bfdf5c4ab921f6b99b07b36205c819564260bd5e096d6a613114f4a64331c795e27b4d4d5f138e4602ed2a45cac28a57dd93723de0324360574ba0f0b0732c3e5f423eb05b1e3518dcbef9018b5440e497f9981b0c12dceb27e7c951cdc3a3236f26c2fffc60f739013f674c096aa6ba969ad2291d1f1ca41e15054193c8c8c15d4702afdda3acf0b8aab30274d2f96b24db5addb57c0709146cb3058aa1f35b54bc544376f4b1d4791e71a5bbc7d2e37e4ae7b56ce77926c4c3cb6b36515e2d2ed4e3c4cfffeb57c2efc1becc0cf421f8f864e7b0284809fcac7863fe8201f47d8bd48ac0879796ffba9b64c8fd001a6a83bfb989671ece19ffd50c6fd0760efa8eea0788ab9f4d10df697ed1cb5e58c91c90d72ffe3d86447c19628d2efa86518e572b00c436f17671fca1beb8c77c74e9690ac111197b14f526d88e02da145dd629a7b5a6a7038b548680830b9c9fdb7aebfe927f3889e7f083f27d20ca7ad4ee698fdd2047f77d5bab199

解密后报文:

XML

<?xml version="1.0" encoding="UTF-8" ?>
<data_content>
    <terminal_id>10001</terminal_id>
    <member_id>100000362</member_id>
    <trans_id>1236546587</trans_id>
    <trade_date>20160425181400</trade_date>
    <succ_amt>1</succ_amt>
    <resp_code>0000</resp_code>
    <resp_msg>交易成功</resp_msg>
    <trans_no>201508060110000524183254</trans_no>
</data_content>

JSON

{
"terminal_id":"10001",
"member_id":"100000362",
"trans_id":"1236546587",
"trade_date":"20160425181400",
"succ_amt":"1",
"resp_code":"0000",
"resp_msg":"交易成功",
"trans_no":"201508060110000524183254"
}

加密数据:

请求响应结果解密后的报文格式需提前联系技术支持进行配置（现支持JSON和XML），输出内容包括

注：
宝付将掉单或超时的订单取出，补发支付结果（结果有成功和失败，不是仅仅发支付成功的订单，请商户务必要根据应答码判断支付结果是成功还是失败，再进行正确的处理），以GET和POST方式发送到商户配置的接收地址，商户接收到支付结果，并且进行相应处理之后，需要商户接收通知的地址在页面上输出 OK 表示接收成功<除了 OK 无任何其他内容>，告诉宝付已经成功接收并处理完毕，宝付系统在未得到商户接收通知成功的反馈时，将通过重发机制再次通知商户（重发次数 2~10 次，请以第一次收到的支付成功的消息为准，避免进行多次充值或支付），直到商户接收成功或达到最大重发次数为止。

2.4.9 网关签约申请

绑定银行卡是指经过持卡人授权将个人银行卡和商户建立绑定关系，支付时不再需要输入银行卡信息。商户通过请求宝付跳转银行页面，用户在银行页面请求并输入短信验证码后完成银行卡的绑定。

交易URL

• 测试环境地址：https://vgw.baofoo.com/cutpayment/protocol/pageSignRequest
• 正式环境地址：https://public.baofoo.com/cutpayment/protocol/pageSignRequest

请求报文

2.4.10 签约结果异步通知

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

返回报文

2.4.11 网关签约预申请

绑定银行卡是指经过持卡人授权将个人银行卡和商户建立绑定关系，支付时不再需要输入银行卡信息。商户通过请求宝付跳转银行页面，用户在银行页面请求并输入短信验证码后完成银行卡的绑定。

交易URL

• 测试环境地址：https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
• 正式环境地址：https://public.baofoo.com/cutpayment/protocol/backTransRequest

请求报文

返回报文

2.4.12 网关确认签约

交易URL

使用2.4.11 网关签约预申请接口返回的url地址

请求报文

2.4.13 网关签约流水结果查询

交易URL

• 测试环境地址：https://vgw.baofoo.com/cutpayment/protocol/backTransRequest
• 正式环境地址：https://public.baofoo.com/cutpayment/protocol/backTransRequest

请求报文

返回报文

2.4.14 渠道解约结果异步通知

配置了解约通知的商户,在收到银行解约通知后,宝付完成商户解约后通知到商户,使用配置的终端进行签名。
例如：bind_id=1202009101455011600000132630&mask_card_holder=三&mask_id_card_no=101001**1234&mask_bank_card_no=6228281234&mask_mobile=131*1234&signature=8ab74c7869632dc395cc945adcc388e6afceb759e4d406c3bb6e0e8002ec422f1615f2a43966d7337dcc57963f18877a959fe9f67b082da2cd95217ba003cc81f07962d665f576509ebc1a38f7ddf2a423775a794b262b7ffc4af615da3ba6bd05d0672c004d7cf80be3ed236f268078bb5c700d4b0a6ae9a0e58f2c782bd6ef
解约配置请联系宝付技术支持及业务人员进行配置。
通知报文

3 附录

3.1 交易状态

3.2 业务应答码

参考业务应答码列表

3.3 银行编码

3.4 交易类型枚举

3.5 商户接口枚举类型

A1、卡类型- card_type

A2、证件类型- id_card_type

商户接口应答码

风控参数字段说明

通用参数

电商

互金消金

航旅

酒店

保险

游戏

大宗

风控参数数据字典

商品类目（prodTypeList）

行业类目（goodsCategory）

证件类型

交易类型（btType）

帐户类型（btAcctType）

国家代码

机场代码

参照国际航空运输协会规定的3位机场代码，国际通用代码，因此每家商户都一致。

省份，区域代码

参照我司省份、区域代码表 –>查看下载