1 文档说明

1.1 文档目的

本文档是为宝付一键绑卡产品定义一个接口规范，以帮助商户技术人员快速接入宝付一键绑卡网关，并快速掌握其相关功能，便于尽快的投入使用。

1.2 阅读对象

• 商户开发人员、维护人员和管理人员
• 宝付一键绑卡产品相关的技术人员

1.3 技术支持联系方式

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

• 技术支持热线：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方式进行通讯。

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解码

1.7 H5接入

商户服务载体为APP

当商户APP跳转至H5完成相关操作关闭页面时，则需要下述方法：
关闭H5页面：bfCloseH5(str)

商户服务载体为uniapp

当商户跳转H5完成相关操作时，商户根据自身业务场景返回至uniapp页面时，则需要下述方法：
关闭H5页面：参数method：bfCloseH5
接收方法参考：

uni.postMessage(OBJECT)
网页向应用发送消息，在的message事件回调event.detail.data中接收消息。

注意事项

js交互时安卓方法对象名为androidYZH，ios交互方法对象名为nativejs由于APP载体H5需提供相关权限信息和配置信息，安卓建议如下配置：

wvShop = (WebView) findViewById(R.wv_body);      
wvShop.getSettings().setJavaScriptEnable(true);//允许与js交互
wvShop.getSettings().setDefaultTextEncodingName("utf-8");//支持中文      
wvShop.addJavaScriptInterface(new JsInterface(this),"androidYZH");//支持调用本地java方法
wvShop.getSettings().setDomStorageEnable(true);//开启dom，允许缓存（防止白屏）
wvShop.setWebViewClient(new WebViewClient)
    {
    //覆盖shouldOverrideUrlLoading 方法
    @Override
    public Boolean shouldOverrideUrlLoading(WebView view ,String url)
    {
        if(url == null )
        return false;
        try
        {
            if(url.startWith("http:") || url.startWith("https:"))
            {
                view.loadurl(url);
                return true;
            }
            else 
            { //如果不是http、https，采用系统浏览器打开
                Intent intent = new Intent(Intent.ACTION_VIEW,Uri.parse(url));
                startActivity(intent);
                return true;
            }
        }
        catch (Exception e)
        { //防止crash
             return false;
        }
    }
    }

1.8 一键绑卡DEMO下载

目前银行要求在商户平台页面上挂持卡人与银行之间的服务协议（快捷支付、协议支付），用户在绑卡时需要用户详细阅读并同意协议，才可以提供协议支付服务。如果不清楚可联系宝付技术支持。一键绑卡挂网协议点击下载

2 业务接口说明

2.1 应用场景

宝付一键绑卡产品是持卡人在经过实名认证的商户平台使用银行卡购买服务或商品前，通过互联网将身份信息提供给商户，商户在得到持卡人授权后，委托宝付跳转至银行端页面，持卡人在银行端页面选择银行卡并授权绑卡的过程，以满足持卡人在商户端使用银行卡支付的业务需求。

场景1：商户在自身收银台页面选择银行

商户在自身收银台页面设计选择银行和借贷记卡的交互，用户在商户页面选择银行和借贷记卡后，直接跳转银行。
商户直跳银行页面模式下,商户获取SN（token）后，直接请求宝付后由宝付转跳转银行页面。
流程图：

调用交易子类说明

场景2：商户跳转宝付页面选择银行

商户收银台只设计一键绑卡入口，然后跳转宝付页面，用户在选择银行和借贷记卡的交互在宝付页面完成，在宝付页面选择后再跳转银行。
商户直跳银行页面模式下,商户获取SN（token）后，请求宝付后会跳转宝付页面，在宝付页面选择银行和银行卡借贷记后跳转银行页面。
流程图：

调用交易子类说明

2.2 业务接口

2.2.1 预签约申请

交易URL

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

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

请求报文

• 说明
  1） “交易类型”
  “交易类型”为请求交易时的交易识别码，该码会直接影响后续交易的交互，请谨慎选择。
  “ 预签约申请”接口中“交易类型”与“一键绑卡签约”接口中“交易类型”成对出现，即“79”对应“80”，“81”对应“82”。
  具体说明参考：“A1交易类型”。
  “79”与“80”为后台模式，“81”与“82”为前台模式。
  后台模式下需要商户自行在收银台放置银行和宝付相关协议，前台模式下可不放时银行及宝付相关协议。
  2）“银行编号”
  “银行编号”在“交易类型”为“79”时，为必传。在“交易类型”为“81”时，如上传则在宝付页面显示上传的银行，如不传则在宝付页面显示所有可选择的银行。
  3）“卡类型”
  “卡类型”在“交易类型”为“79”时，为必传。在“交易类型”为“81”时，如上传则在宝付页面显示上传的卡类型，如不传则在宝付页面显示所有可选择的卡类型（不限制卡类型则该字段为空）。
  4）“签名方式”
  “签名方式”用于标识算法方式，国密方式取值为：10；国际算法可默认不传。默认不传为国际算法。
  5）“加密证书序列号”“签名证书序列号”
  “加密证书序列号”和“签名证书序列号”在“签名方式”为国密方式（取值为10）时，必须上传，在“签名方式”为国际算法时，可传可不传。

返回报文

-说明
1）“加密证书序列号”“签名证书序列号”
“加密证书序列号”和“签名证书序列号”在“签名方式”为国密方式（取值为10）时必返回，在“签名方式”为国际算法时如请求时上送则返回。

2.2.2 一键绑卡签约

交易URL

测试环境地址：一键绑卡预申请中返回的url地址

正式环境地址：一键绑卡预申请中返回的url地址

请求报文

• 说明
  1）“交易类型”
  在“预签约申请”中“交易类型”为“79”时，此处“交易类型”为“80”。
  在“预签约申请”中“交易类型”为“81”时，此处“交易类型”为“82”。

2.2.3 一键绑卡商户跳转

交易URL

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

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

请求报文

返回报文

-说明
1）提交参数对象：

params返回示例：
[{“key”:”epccGwMsg”,”value”:”PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cm9vdCB4bWxucz0ibmFtZXNwYWNlX3N0cmluZyI+PE1zZ0hlYWRlcj48U25kRHQ+MjAyNC0xMi0wNVQxNDoxODo0MjwvU25kRHQ+PE1zZ1RwPmVwY2MuMTA1LjAwMS4wMTwvTXNnVHA+PElzc3JJZD5HNDAwMDMxMTAwMDAxODwvSXNzcklkPjxEcmN0bj4yMTwvRHJjdG4+PFNpZ25TTj40NDAyMzgyODIxPC9TaWduU04+PE5jcnB0blNOPjQyNzU4MTQ1ODc8L05jcnB0blNOPjxEZ3RsRW52bHA+TUlHTkFpRUFoMnkxZ2V6R3hlNTN5K2YzUXFEN3pzQTV2VnRYVFJxc0paUjgwemlpUnJvQ0lRQ0dTVWp2REtadTVjMXBsMFRET0VsaGN1eC9PeGZkU3ZXb1pWRHR6dVAvU1FRZ0Y2K0tvL3I4clg1dWVtRVJpUzRQbzQyZEIwbit2allwM2w2WEhqdEcvZzhFSS9nZDliNExUNlRkbkQzdHdtZjJJRHFuUEtLZXNiQ2Qva2dsL1FMZkRkRWcxNHpXPC9EZ3RsRW52bHA+PC9Nc2dIZWFkZXI+PE1zZ0JvZHk+PFN5c1J0bkluZj48U3lzUnRuQ2Q+MDAwMDAwMDA8L1N5c1J0bkNkPjxTeXNSdG5EZXNjPuaIkOWKnzwvU3lzUnRuRGVzYz48U3lzUnRuVG0+MjAyNC0xMi0wNVQxNDoxODo0MjwvU3lzUnRuVG0+PC9TeXNSdG5JbmY+PEJpekluZj48VHJ4Q3RneT4wMjAwPC9UcnhDdGd5PjxUcnhJZD4yMDI0MTIwNTEwMDAwMDAwMDAxNDkzNjMwMjEwOTAzPC9UcnhJZD48Qml6U3RzQ2Q+MDAwMDAwMDA8L0JpelN0c0NkPjxCaXpTdHNEZXNjPuaIkOWKnzwvQml6U3RzRGVzYz48UmRyY3RVcmw+aHR0cHM6Ly93YXAuY2diY2hpbmEuY29tLmNuL2g1LW1vYmlsZWJhbmstYXBwL3Nlc3Npb24vdW5pb25wYXkvdGhpcmRiaW5kLmxneDwvUmRyY3RVcmw+PC9CaXpJbmY+PFNlYz5aV1lBa3RCZXhHZ3JlVHFWcW1ZTXkyNnNOUzFwQlEvNUFLR0pFMW9JaFJyWHJTZ3dOanJqU3IyMDA5bmNqbTJ5WU8ra2gvOUFrOG1HckZJK1B0Q1RBd2cvRm83SW1RKzB1MjZiSm5YTXpoOXV6S0dVK3BDby9IV0o2YmhHb2I2MCtFOUZwV2JCTktTalNHYVdBTE9PRllaQjJTdkNrNzdOYk9iYlRpUFNrSG9XZm9JbEE1Q0dPemRFRndCMEh2YzZ2T2l1Rlgxc0k2bXR4VzlVVTdlamNMRm1ZazBITkYwTE1QRzBuUjF4a3J3aVNPczBraWQ5c2FUeTVCbVRBUzc3WVpEN2srM0Y5bDBDWlV3QnNyTUN5bVl6V0JSMC9KQzBpSlhVOFhVNW9OWGhPNW5Wa1N4amt5VVFoTVdXWTE3U1huWk9BQjhGbW93RVhrRXVBMHViYXFBZzIvZmVrTGxaWWZEYjU1TDZCV0dLWDBWYUY5eDJUaEpFTGp4bzBFSTllekM0aHVjUHZjZnVRUWZhbDJlbE1aWFJnWEppWG14QTJYT0xUL0lTaHY3ZnBhT0pUemZuaTZzbEJSTkRhZmJMaVpQcEZSMUxkMzFWclpFUVZUYm9rOGdCM0tibGtVY0dyVjJ2Zml2QTBxZEMweWtIQXZtZFBPUlRpU2VpNUlLcWxQWkdhaDRYeTQ2eG5zUTVJRG9URUFOQ3M3VDBWOVY4QkNoUElpQkwvL3VIOVBvaXBzVHZRYjgvZzNBY3J0eGtvNmhtL3JZQm5PUGFzcSswTTVDallBPT08L1NlYz48L01zZ0JvZHk+PC9yb290Pg0Ke1M6TUVZQ0lRRDhnS2IvMUFKbWgvVVZ4YURBUjZKcXlMbk91K25LNzJhKzBsMkhsaklEU0FJaEFMRFVZQzJqWldFLysrYzFiVC9DY203REUyNFpCSXJ5bkxZOFV5bm5DL0hOfQ==”}]

2.2.4 历史签约结果查询

交易URL

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

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

请求报文

-说明
1）“签名方式”
“签名方式”用于标识算法方式，国密方式取值为：10；国际算法可默认不传。默认不传为国际算法。
2）“加密证书序列号”“签名证书序列号”
“加密证书序列号”和“签名证书序列号”在“签名方式”为国密方式（取值为10）时，必须上传，在“签名方式”为国际算法时，可传可不传。

返回报文

-说明
1）“加密证书序列号”“签名证书序列号”
“加密证书序列号”和“签名证书序列号”在“签名方式”为国密方式（取值为10）时必返回，在“签名方式”为国际算法时如请求时上送则返回。

2.2.5网关签约流水结果查询

交易URL

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

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

请求报文

-说明
1）“签名方式”
“签名方式”用于标识算法方式，国密方式取值为：10；国际算法可默认不传。默认不传为国际算法。
2）“加密证书序列号”“签名证书序列号”
“加密证书序列号”和“签名证书序列号”在“签名方式”为国密方式（取值为10）时，必须上传，在“签名方式”为国际算法时，可传可不传。

返回报文

-说明
1）“加密证书序列号”“签名证书序列号”
“加密证书序列号”和“签名证书序列号”在“签名方式”为国密方式（取值为10）时必返回，在“签名方式”为国际算法时如请求时上送则返回。

2.2.6异步结果通知

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

异步结果通知

• 说明：
  1）“账户信息”
  “账户信息”默认脱敏，如果卡号信息，则联系宝付业务人员配置后返回。
  2）“加密证书序列号”“签名证书序列号”
  “加密证书序列号”和“签名证书序列号”在“签名方式”为国密方式（取值为10）时必返回，在“签名方式”为国际算法时如请求时上送则返回。

3 应答码

3.1商户接口应答码

3.2 宝付业务应答码

更多应答码，详见业务应答码附件

4 数据元类型说明

A1交易类型

A2卡类型- card_type

A3证件类型- id_card_type

A4银行编码

• 更多银行编码缩写下载
  • 各银行缩写

5 风控参数字段说明

通用参数

风险信息域risk_info

国家代码

• 更多国家代码下载
  • 国家代码

机场代码

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

省份，区域代码

参照我司省份、区域代码表

• 省市区编码下载
  • 省市区编码