银账通接口(银盛存管)

版本说明

目录

目录 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.1 获取token

4.2.2 图片上传

4.2.3 商户进件

4.2.4 商户进件查询

4.2.5 商户进件异步通知

4.2.6商户报备

4.2.7商户报备查询

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 获取token

该接口用户商户进件接口调用之前获取token

请求URL

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

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

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

data

4.2.2 图片上传

该接口用于商户进件流程获取token之后进行图片上传，不同类型商户需上传图片类型请参考附表2

注：此接口直接用form表单形式提交图片。

请求URL

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

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

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

data

4.2.3 商户进件

该接口用于入驻平台的企业，小微及个人商户进件

商户进件流程说明：

1. 获取token

2. 进行图片上传

3. 调用商户进件接口完成进件。

请求URL

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

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

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

4.2.4 商户进件查询

该接口用于进行商户进件状态查询

请求URL

测试 url: http://bd4-vtest.ysepay.com/api/query/merchant/registry

生产 url: https://yzt.ysepay.com:8443/api/query/merchant/registry

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

data

4.2.5 商户进件异步通知

异步通知商户进件接口审核结果

通知内容说明

4.2.6 商户报备

用于商户的微信和支付宝报备（仅适用于商户进件（活体）接口进件的商户）。

请求URL

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

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

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

4.2.7 商户报备查询

用于商户的微信和支付宝报备的结果查询（仅适用于商户进件（活体）接口进件的商户）。

请求URL

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

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

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

4.2.8 商户报备查询（带第三方商户号返回）

用于商户的微信和支付宝报备的结果查询（仅适用于商户进件（活体）接口进件的商户）。

请求URL

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

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

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

data中的参数集合

4.2.9 根据银盛商户号查询应用商户号

根据银盛商户号（X开头）查询应用商户号（自己命名的商户号）

请求URL

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

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

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

4.2.10 商户修改结算方式

此接口用于更改B端子商户的账户结算方式

请求URL

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

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

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

4.2.11 商户修改结算卡

此接口用于更改B端子商户的结算卡信息，先使用图片上传接口上传三张图片（35:结算银行卡正面照、36:结算银行卡反面照、32:已签字盖章的结算卡修改申请单照片），三张图片上传之后获取picId的密文再调用此接口。如果子商户类型为企业，则只能更改为此商户的对公银行账户；如果此子商户类型为个体，则只能更改为此商户法人的对公户或法人银行卡；如果此子商户类型为小微，则只能更改为此商户法人的银行卡。

请求URL

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

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

编码格式 : UTF-8

调用方式：POST

请求参数列表

返回参数列表

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}