银账通接口(银盛存管)

版本说明

目录

目录 2

1.概述 7

2.接口通讯 7

2.1交互方式 7

2.2报文结构 7

2.3消息码列表 8

2.4 系统对接前的准备工作及注意事项 9

3.产品介绍 9

3.1场景介绍 9

3.2 功能描述 9

3.3 业务流程 9

4 接口说明 10

4.1报文规范 10

4.2后台接口 10

4.2.11 用户开户 10

4.2.12 手机验证码 11

4.2.13 注册手机号绑定 12

4.2.14修改注册手机号 31

4.2.15 用户信息查询 13

4.2.16 银行卡绑定申请 14

4.2.17 银行卡绑定确认 15

4.2.18 绑定银行卡查询 16

4.2.19解绑银行卡 17

4.2.20 卡bin查询 18

5 返回码 52

6 业务错误码 54

7 安全要求 54

7.1 公钥和私钥使用说明 54

7.2 加解密和签名方案 55

7.2.1 请求报文的加密方案 55

7.2.2 请求报文的签名方案 57

7.2.3 响应报文的解密方案 58

7.2.4 响应报文的验签方案 58

7.2.5 异步通知报文的验签方案 59

1.概述

本文档为银账通系统的对外接入的技术指南，方便商户快速接入。

本文档的目标读者为技术人员

银账通保留对该文档的最终解释权与修改权

2.接口通讯

2.1交互方式

消息请求基于 HTTP/HTTPS 的 POST 方式。

Content-Type 设置" application/x-www-form-urlencoded;charset=UTF-8 "。

2.2报文结构

报文统一以key/value方式，如下：

timeStamp=“时间戳, msg=“加密业务数据”, src=“消息来源”, version=“版本号”,sign=“签名数据”, check=“AES密钥密文”, certId=“商户号”, msgCode=“消息码”

参数说明：

以用户信息余额查询报文举例，报文示例如下

{timeStamp=2018-12-16 10:59:16, msg=yC6+sCdO54gddxPHRHyshX7yie0Qiv7mBiHpW64RGvzuMMq//h4R1v8hqA2n+qwSIISuCUJ7FnKmcKetBo6wxUyQm/5KNyicYYbmSL8wkGO/MKVn08LyILt2/LeftQ5R3NKXIyYaYMS8p2OjOlShZZFt2HZDK3PVvrC2v43GMBop973M1ZlSqjv/UiE+eup3,

norce=cf262c0aa38243979377f04d39865c25,

src=02,

version=1.0, sign=MeQLeL31IwO75hC/GtY3W0M29SCjVUqlm68nOuL7HGFJlNq8FkB1eqfHUenM1O2mn8r5sedEYWbuUUiJi5mgIN5RIHaRP39O8kWwCk7/Al/S+H8gBP9BGU8TdplYGJOzszcD6J3T4To3+3EbRLfJ7/nJaI/UOQvGhNdqA0ng1/s=, check=bjCQfmaGoRhUGZDBoPPXvQjvZaLwMAxC3tLDFyCydcF1Kv6Qj4oH5ggPXoXZ66BHuU4aM73MSHmwgdYxhp1x1VRMPWWw9awlCBI4FYBc/8wClygtiz/l6MAIZk8JfmGXrMADYBlifEXgZ+oQkrVa9tYV8x8idI8hll/yDqE0IXw=,

certId=s0005,

msgCode=searchUser

}

msg加密业务数据明文内容为：

{"appSecret":"qY2Q+f7ptLK2/y6tUDMLn42swYklNmstSwEYmCy/DQM=","appUserCode":"zj-05","isSearchBalance":"Y"}

2.3消息码列表

2.4 系统对接前的准备工作及注意事项

测试环境可联系商户对接人员获取app密钥及App用户号及证书。

测试环境对接完成可联系对接人员获取线上证书及相关密钥。

3.产品介绍

3.1场景介绍

适用于商家调用银账通的API接口，在合作商户app或网站上实现用户及商户开户、绑卡、充值、提现、支付、解绑卡等功能。

3.2 功能描述

本文档描述银账通开发项目与合作商户相关系统之间的报文格式、接口规范及安全规范。

3.3 业务流程

银账通合作商户的接入方式，根据业务模式进行接入：

1. 不验证：用户在交易过程中，银盛不进行任何验证，所有验证交由合作商户完成。

2. 短信验证：用户在交易过程中，银盛下发短信验证码进行短信验证。

4 接口说明

描述：第三方app后台直接请求银账通后台接口

4.1报文规范

请求参数是否必填，M表示必填，O表示选填

4.2后台接口

4.2.1 用户开户

该接口用于个人用户开户，即C端用户创建商户，如企业商户开户请使用4.2.26商户进件接口。如只有B端商户注册则不用对接用户部分。

开户流程

1. 调用开户接口

2. 开户成功后进行注册手机号绑定，并进行短验

3. 用户回填验证码，完成开户操作。

请求URL

测试 url: http://bd4-vtest.ysepay.com/api/applyAccount

生产 url: https://yzt.ysepay.com:8443/api/applyAccount

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

4.2.2 手机验证码

1．注册手机号绑定接口调用之前调用此接口（funcode=B1），系统将向待绑定手机号码发送动态短信验证码。

2．修改注册手机号前调用此接口（funcode=B2），系统将向待修改手机号码发送动态短信验证码。

请求URL

测试 url: http://bd4-vtest.ysepay.com/api/verificationCode

生产 url: https://yzt.ysepay.com:8443/api/verificationCode

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

4.2.3 注册手机号绑定

注：开户接口调用之后需要调用该接口绑定手机号，本交易由商家app后台发起，银账通系统直接返回

请求URL

测试 url: http://bd4-vtest.ysepay.com/api/registerMobileBind

生产 url: https://yzt.ysepay.com:8443/api/registerMobileBind

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

4.2.4 修改注册手机号

用于个人用户修改用户注册手机号

请求URL

测试 url: http://bd4-vtest.ysepay.com/api/registerMobileModify

生产 url: https://yzt.ysepay.com:8443/api/registerMobileModify

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

4.2.5 用户信息查询

该接口用于进行用户信息的查询。

请求URL

测试 url:http://bd4-vtest.ysepay.com/api/getAccountInfo

生产 url:https://yzt.ysepay.com:8443/api/getAccountInfo

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表*

data

4.2.6 银行卡绑定申请

用户开户流程（包括开户+手机号绑定）后可进行银行卡绑定，可用于在商家app进行消费。

绑卡流程：

1. 调用银行卡绑定申请接口，银行系统会发送短信验证码给用户银行预留手机号

2. 调用银行卡绑定确认接口，进行短信确认即可。

请求URL

测试 url: http://bd4-vtest.ysepay.com/api/bindingBankCard

生产 url: https://yzt.ysepay.com:8443/api/bindingBankCard

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

data

4.2.7 银行卡绑定确认

银行卡绑定申请接口调用之后，发起银行卡绑定确认交易。

请求URL

测试url: http://bd4-vtest.ysepay.com/api/confirmAndBindingCard

生产url: https://yzt.ysepay.com:8443/api/confirmAndBindingCard

编码格式 : UTF-8

调用方式：POST

请求参数列表

参数

返回参数列表

4.2.8 银行卡绑定申请（新）

此绑卡接口与旧的银行卡绑定接口（4.2.16&2.2.17 ）参数一样，区别是原有银行卡绑定接口只支持快捷协议银行卡绑卡，而此银行卡绑定接口支持所有银行卡绑卡，如果银行卡支持开通快捷协议，则可以进行充值、消费、提现，不支持开通快捷协议的银行卡只能提现。

绑卡流程：

1. 调用银行卡绑定申请接口，银行系统会发送短信验证码给用户银行预留手机号

2. 调用银行卡绑定确认接口，进行短信确认即可。

请求URL

测试 url: [http://bd4-vtest.ysepay.com/api/bindingBankCardNew

生产 url: https://yzt.ysepay.com:8443/api/bindingBankCardNew

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

data

4.2.9 银行卡绑定确认（新）

银行卡绑定申请（新）调用之后，发起银行卡绑定确认交易。如果开通快捷协议，返回：“绑卡成功，此银行卡可支持提现和支付”；如果没有开通快捷协议，返回：“绑卡成功，此银行卡可支持提现”

请求URL

测试url: http://bd4-vtest.ysepay.com/api/confirmAndBindingCardNew

生产url: https://yzt.ysepay.com:8443/api/confirmAndBindingCardNew

编码格式 : UTF-8

调用方式：POST

请求参数列表

参数

返回参数列表

4.2.10 绑定银行卡查询

查询用户绑定银行卡。

请求URL

测试 url: http://bd4-vtest.ysepay.com/api/userBindingCardList

生产 url: https://yzt.ysepay.com:8443/api/userBindingCardList

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

data

bankCardList

4.2.11 解绑银行卡

该接口用于对用户已绑定银行卡进行解绑操作。

请求URL

测试 url: http://bd4-vtest.ysepay.com/api/unbindBankCard

生产 url: https://yzt.ysepay.com:8443/api/unbindBankCard

编码格式 : UTF-7

调用方式：POST

请求参数列表

返回参数列表

4.2.12 卡bin查询

商户APP可调用该接口查询银行卡卡bin信息，以便于展示银行LOGO，以及针对贷记卡要求商户及时补充CVV、安全码等。

请求URL

测试 url: http://bd4-vtest.ysepay.com/api/cardInformation

生产 url: https://yzt.ysepay.com:8443/api/cardInformation

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

data

-data-

5 返回码

附表1

附表2

图片类型的必要性，打钩为必填项：

附表3

6 业务错误码

7 安全要求

7.1 公钥和私钥使用说明

生产环境的公钥证书为银盛提供，此公钥证书有两个作用：
1、对所有接口返回的数据进行验签。
2、对随机字符串进行加密，该随机字符串和参与AES对称加密请求参数的随机字符串一致

私钥用于商户签名，格式为xxx_xxx.pfx

7.2 加解密和签名方案

加解密和签名方案分为请求报文的加密签名、响应报文的解密验签、异步通知报文的验签，

其中异步通知报文的验签和响应报文的验签规则是相同的，只是参数不同以及异步通知报文不需要解密业务数据。流程图如下

7.2.1 请求报文的加密方案

本方案采用AES（对称加密算法）和RSA（非对称加密算法）组合的方式进行加密。AES用于业务信息的加密；RSA用于AES密钥的加密传输，

AES加密流程：业务参数组装成JSON格式，直接使用随机生成的AES密钥对JSON数据进行AES加密处理，同时进行BASE64编码处理，得到请求参数msg。

AES加密示例

RSA公钥加密流程：商户使用银账通公钥对AES密钥明文进行加密，同时进行BASE64编码处理，得到请求参数check。

RSA公钥加密示例

7.2.2 请求报文的签名方案

RSA私钥签名：对除了sign参数以外的请求参数做字典排序，并将参数以key=value形似，并用&符号连接成字符串，形如check=123456&msg=xxxx&msgCode=xxx。对拼接后的字符串使用私钥做签名处理，得到参数sign。

签名示例

7.2.3 响应报文的解密方案

AES解密流程：首先BASE64解码加密数据data，根据AEA密钥对数据进行解密处理，转成字符串得到解密数据data

7.2.4 响应报文的验签方案

{"charset":"UTF-8","data":"eyJhbW91bnQiOiIxMC4wIiwibm90aWZ5VGltZSI6IjIwMTgtMTItMDcgMTc6MjU6MTUiLCJvcmRlck5vIjoiNDQ0NDU2NjIyMyIsInNlcnZpY2VJZCI6IjE4MDIwNTIxMTcwODAwMzkiLCJzdGF0dXMiOiIwNCIsInRyYWRlU24iOiIzMjEyMDE4MTIwNzYyNzEzMjI0OTQifQ==","sign":"UUfJCDZYBFk/Tqke3XsN63RBtldyzdq8vK4k74SIkpQu6eaxBGlkd/4AjEkk58ZlWYzXcU4pifDHTjAE2CdGMrS79zZwQ1zaaA2xSZMnvtBVJUryUau6e0E2w4/TXWXC/PrPhhVCI7PD8e44Cnii4yXfFhW4ETtdrc4+zfngKEI=","timeStamp":"2018-12-07 17:26:07","version":"1.0"}

商户端接收到银账通服务端通知的数据后，对所有除了sign以外的参数做字典序排列，并将参数以key=value形式，用&符号进行拼接形成字符串，形如code=200&data=DpAq6Fybf2HDHgxc6k540BKbKem+sBHSsaEzrYNT2gUU6hfOm7yEnDs/vWB9qlmHuTnTRUkdABzCOE3nF2il9yW0G3+o6vyNlEidq2CFuDA=

&msg=OK&norce=5ece581f35b54413b6f5d539de40a527&timeStamp=2018-12-16 14:29:19，然后使用银账通公钥做验签处理，验签通过后，方可进行后续处理。

特别注意：sign参数值为BASE64编码后的结果，验签前需要对sign进行解码处理。 data参数值为BASE64编码结果，后续业务处理也需要进行解码处理，解码后为普通JSON格式字符串，具体参数见data域说明

7.2.5 异步通知报文的验签方案

{"charset":"UTF-8","data":"eyJhbW91bnQiOiIxMC4wIiwibm90aWZ5VGltZSI6IjIwMTgtMTItMDcgMTc6MjU6MTUiLCJvcmRlck5vIjoiNDQ0NDU2NjIyMyIsInNlcnZpY2VJZCI6IjE4MDIwNTIxMTcwODAwMzkiLCJzdGF0dXMiOiIwNCIsInRyYWRlU24iOiIzMjEyMDE4MTIwNzYyNzEzMjI0OTQifQ==","sign":"UUfJCDZYBFk/Tqke3XsN63RBtldyzdq8vK4k74SIkpQu6eaxBGlkd/4AjEkk58ZlWYzXcU4pifDHTjAE2CdGMrS79zZwQ1zaaA2xSZMnvtBVJUryUau6e0E2w4/TXWXC/PrPhhVCI7PD8e44Cnii4yXfFhW4ETtdrc4+zfngKEI=","timeStamp":"2018-12-07 17:26:07","version":"1.0"}

商户端接收到银账通服务端通知的数据后，对所有除了sign以外的参数做字典序排列，并将参数以key=value形式，用&符号进行拼接形成字符串，形如charset=UTF-8&data=eyJhbW91bnQiOiIxMC4wIiwibm90aWZ5VGltZSI6IjIwMTgtMTItMDcgMTc6MjU6MTUiLCJvcmRlck5vIjoiNDQ0NDU2NjIyMyIsInNlcnZpY2VJZCI6IjE4MDIwNTIxMTcwODAwMzkiLCJzdGF0dXMiOiIwNCIsInRyYWRlU24iOiIzMjEyMDE4MTIwNzYyNzEzMjI0OTQifQ==&timeStamp=2018-12-07 17:26:07&version=1.0，然后使用银账通公钥做验签处理，验签通过后，方可进行后续处理。

特别注意：sign参数值为BASE64编码后的结果，验签前需要对sign进行解码处理。 data参数值为BASE64编码结果，后续业务处理也需要进行解码处理，解码后为普通JSON格式字符串，具体参数见data域说明 {"code":200,"message":"成功","data":null,"list":null}