一网通账户

API文档与说明

1、报文规范

1.1 交互方式

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

Content-Type设置”application/json; charset=UTF-8”。

测试环境(公网):

https://sharpay.csuat.cmburl.cn/gateway

生产环境(公网):

https://sharpay.paas.cmbchina.com/gateway

 

1.2  数据类型

String(x)表示最大长度为x字节的变长字符串,如有固定长度等特殊要求在接口文档中说明。

长度的计算说明:所有长度均按字节计算,中文算两个字节,英文、数字算一个字节。


1.3  报文传递条件

M  必需填写的参数

C  某些条件成立时必需填写的参数。具体条件在描述中说明

O  可选择填写的参数


1.4  字符及编码

报文采用Unicode字符集,GBK编码方式。


1.5  报文结构

为了更好的区分国密报文和非国密报文,平台会根据合作方平台商户号设置算法类型,根据设置的算法类型指定前往验密的服务是国密服务还是非国密服务。

报文统一为json格式字符串,如下

{

“version“:报文版本号

“transType”:交易类型

“cprInsCode”:合作机构代码

“msgKey”:交易流水

“transData”:交易报文

“sgnSeq”:合作方证书序列号

“encSeq”:招行证书序列号

“signature”:签名数据

“digitalEnve“:数字信封

}

逐域释义:

报文域                

报文域含义                

取值说明                

填写规则                

最大长度                

version                

报文版本号                

按照本规范默认填写“1.0”                

必填                

6                

transType                

交易类型                

详见交易类型列表                

必填                

4                

cprInsCode                

合作方平台编码                

合作方机构的唯一识别码,由招行分配。                

必填                

15                

msgKey                

交易流水                

由交易发起方生成和填写。各合作商户保证内部唯一,招行返回报文原样应答。建议使用合作方机构代码+14位日期时间+补足32位。如:000001201803222054590000000001                

必填                

40                

transData                

交易报文                

具体交易的报文,不同交易字段不同,采用json格式。                

必填                

1024*200                

sgnSeq                

签名验签证书序列号                

签名验签证书序列号(全部为16进制小写)

预留非必填                

128                

encSeq                

加密解密证书序列号                

加密解密证书序列号(全部为16进制小写)

预留非必填                

128                

signature                

签名数据                

签名方案详见加解密和签名验签                

必填                

512                

digitalEnve

数字信封                

详见加解密和签名验签                

如有加密字段则必填                

512                

报文示例如下:

? {

"version": "1.0",

"transType": "0001",

"cprInsCode": "000001",

"msgKey": "000001201803222054590000000001", "transData": "{

\"param1\":\"aaa\",

\"param2\":\"bbb\"

}",

"sgnSeq": "1111111111",

"encSeq": "1111111111", "signature":

"MEUCIEmDeWoaUJzvL8b3SRAF5tTFOvNkl+M8YB3NFW1jn/s2AiEAyZyPUXLM4Bj89WCmTGjKWFovYk

HH0VLpV3FfphhOQ64=",

"digitalEnve":

"MIGMAiB8UDQPSvrkUDEub59+gNjSrC0K7AWtK2tqh+Fdl2BDtwIhAJ8BtHGj Od/Uy9wCirLXOfWrOkv8JSZFZHdquwdz9f5JBCAp9YSo/6BMjprCySH4XHyauDEZtUKFRXXwd0fQ253

2LQQjvfKsAPjvfghy9cMNSmpjf78DCmgyHTBjgmnkpVpry/5l6dE="

}

注:此报文示例仅说明报文格式,signature的内容并非按照签名方案算出的签名值。

 

1.6  交易类型列表

业务类型                

交易子类                

交易类型编码                

开户业务                

三类户开户申请验证码                

0001                

申请验证码异常查询                

0004                

三类户开户发起                

0008                

开户结果查询                

0005                

二类户开户申请验证码                

0015                

二类户开户发起                

0016                

解约                

0006                

解约异常查询                

0007                

同时开立二三类户发验证码                

0009                

同时开立二三类户发起                

0010                

三类户升级二类户发起                

0011                

三类户升级二类户结果查询                

0012                

影像上传                

0013                

开三类户获取风控策略                

0017                

开二类户获取风控策略                

0018                

同时开二三类户获取风控策略                

0019                

三类户升级二类户申请验证码                

0020                

三类户升级二类户获取风控策略                

0021                

充值提现业务                

绑定账户充值                

1001                

绑定账户充值结果查询                

1002                

绑定账户提现                

1003                

绑定账户提现结果查询                

1004                

非绑定账户充值                

1005                

合作方代发充值结果查询                

1006                

合作方代发充值                

1007                

合作方代发充值回退                

1008                

充值可转账金额查询                

1009                

提现可转账金额查询                

1010                

查询业务                

二三类户状态及绑卡信息查询                

3001                

余额及状态查询                

3002                

按协议号查询户口信息                

3004                

活期交易查询                

3005                

清算对账                

对账文件下载地址查询                

4001                

转账业务                

钱包转账暂挂                

5001                

钱包转账解暂挂                

5002                

钱包转账                

5003                

钱包转账交易状态查询                

5004                

C2C红包                

钱包C2C红包发放                

6001                

钱包C2C红包领取接收                

6002                

钱包C2C红包退回                

6003                

钱包C2C红包交易状态查询                

6004                

绑定管理                

添加绑定账户发起                

7001                

添加绑定账户结果查询                

7002                

删除绑定账户发起                

7003                

删除绑定账户结果查询                

7004                

维护业务                

三类户设置非绑资金入账标志发起                

8001                

三类户设置非绑资金入账标志结果查询                

8002                

账户冻结发起                

8003                

账户冻结结果查询                

8004                

维护手机号发起                

8005                

维护手机号结果查询                

8006                

账户解冻                

8007                

账户解冻结果查询                

8008                

维护手机发验证码                

8009                

公共业务                

发送短信验证码                

9001                

 

 

1.7  公共数据对象

  RiskInfo

参数列表                

字段名                

类型                

长度                

M/O                

字段描述                

phyId                

物理ID                

String                

100                

M                

appid、mac                

deviceOs                

操作系统类型                

String                

1                

O                

0.其他
  1.iOS
  2.Andorid
  3.iPad
  4.Surface
               

deviceImei                

IMEI                

String                

15                

C                

ANDROID设备时上送                

deviceIdfa                

IDFA                

String                

36                

C                

IOS设备时上送                

ipv4                

IP地址                

String                

64                

C                

Ipv4、ipv6两者选其一(必送一个)                

ipv6                

IPv6                

String                

128                

C                

Ipv4、ipv6两者选其一(必送一个)                

lbs                

经纬度                

String                

64                

M                

格式:经度|纬度                


1.8 加解密和签名验签

    1.8.1  名词解释


名称              

描述                

备注                

1                

RSA算法                

国际算法                

无特殊条件,新增商户禁用该算法                

1

SM2 算法                

基于椭圆曲线的国密加密算法                

本文档采用该算法,算法标准参考国密局标准制定                

3

敏感信息                

包含但不限于:个人银行账户编号、个人银行账户名称、个人证件号、个人手机号、个人支付账户编号。                

采用数字信封方式进行加解密                

4

数字信封                

一种混合加密模式,包含非对称加密算法和对称加密算法,用于加密报文中的敏感信息                

本文档采用 SM2+SM4 方式                

5

数字签名                

用于鉴别信息的完整性和真实性及发送方的身份。                

采用 SM2withSM3 签名算法进行签名。                

6

SSL 层加密                

安全套接层(Secure Sockets Layer),在传输层对网络连接进行加密。                

采用 https 单向认证,暂采用 HTTPS(RSA2048)方式进行通讯层加密处理。建议客户端验证服务端密钥链或 IP                


   1.8.2  算法说明

约定使用国密标准算法(SM2),商户须支持如下:

序号                

类型                

国际标准算法                

备注                

1                

数字签名的签名验签                

SM3withSM2                

PKCS#1   Padding                

国密标准                

2                

敏感信息加解密、对账文件加解密                

对称密钥加密方式:SM2加密                  

敏感信息加密方式:SM4_CBC_PKCS#5 Padding                

国密标准                

3                

SSL   层加解密                

TLS1.2                

严禁使用 MD5RC4   算法;                

RSA 算法要求大于 1024                  

SM2   要求大于 128                

SSL 握手需支持单向认证                

注:生产环境商户机构与银行所使用密钥自行生产


1.8.3 使用密钥信息

序号                

密码资源类型                

来源                

用途                

存放位置                

有效期                

1                

SSL 服务私钥                

自行产生                

SSL 数字密钥对应的私钥。                

SSL 设备中或   jboss 等网关系统                

36 个月                

2                

SSL 服务公钥                

认证机构签发                

SSL 数字密钥的公钥。                

SSL 设备中或   jboss 等网关系统                

36 个月                

3                

签名解密私钥                

自行产生                

签名报文;数字信封解密。                

签名验签设备中或安全系统中                

36 个月                

4                

验签加密公钥                

自行产生                

提供给平台验签;数字信封加密。                

提供给平台或商户                

36 个月                

5                

敏感信息对称密钥                

发起方提供,在报文中                

敏感信息加解密                

报文中(加密后)                

一次一密                

6                

对账文件公私钥                

(可选)                

自行产生                

(同签名加密公私钥)                

用于对账文件签名加密                

签名验签设备中或安全系统中                

36 个月                

注:

1.签名验签证书、加密解密证书可共用一张即可

2.SSL证书需区别于签名加密证书


1.8.4  加解密流程说明

1.8.4.1  SSL层加解密

1.     HTTPS采用单向验证方式,发起方作为客户端,接收方作为服务端

2.     需支持TLS1.2协议,加密算法套件严禁使用弱算法

1.8.4.2   字符及编码

报文采用Unicode字符集,GBK编码方式。

1.8.4.3   敏感信息加解密

1.         发起方自行产生 128 位长度二进制随机数作为“SM4 对称密钥”;

2.         发起方使用“SM4 对称密钥”分别对整个transdata内的json数据进行SM4 加密并 Base64 编码后,将其存储在transdata字段;

3.         发起方采用 SM2 加密“对称密钥”并 Base64 编码,放在指定的“数字信封”字段。

4.         接收端采用“密钥序列号”所对应的私钥解密“数字信封”获得 “对称密钥”明文;

5.         接收方使用“对称密钥”调用 SM4 算法对敏感信息进行解密;



1.8.4.4    数字签名签名验签


1.         发起方采用 SM3withSM2 签名方式,对报文进行签名并存入在报文中的“数字签名”域,接收方采用发起方公钥对报文进行验签,验证报文是否被篡改;

2.         国密版本的签名详细算法:对 transData字段的base64密文进行整体加签,加签方式如下。

3.         用 SM3 摘要算法计算上一步的transData密文,并将结果转换成 16 进制表示的字符串(大写);

4.         用发起方的私钥对上一步得到的哈希值字符串生成签名值 signature。签名后的结果用 BASE64 进行编码,没有回车换行符。(签名算法采用 SM3withSM2,PKCS#1 方式)

5.         发起方在报文中传递“签名密钥序列号”作为唯一标识,接收方通过“签名密钥序列号”找到相应的密钥,进行验签;

6.         当密钥更新时,发起方与接收方可能有都存在两套密钥,密钥过渡期,发起方可自行选择密钥进行签名,接收方应当正确识别选用的密钥序列号对应的密钥实体进行验签。要求在更新截止日期前双方完成密钥更换,实现平滑过渡。

 

1.8.4.5   密钥更新

1.         当密钥更新时,发起方与接收方可能有都存在两套密钥,密钥过渡期,发起方可自行选择密钥进行签名,接收方应当正确识别选用的密钥序列号对应的密钥实体进行验签。要求在更新截止日期前双方完成密钥更换,实现平滑过渡。

2.         当密钥更新时,约定将公钥进行线下方式加密送达给对方。

1.8.4.6   对账文件加解密(可选)

平台产生的对账文件,采用对方的公钥进行加密,加密算法与上述一致;商户需使用商户私钥进行解密,以保证对账文件的完整性和安全性。


附件:招商银行一网通账户API输出接口V2.13.pdf