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.其他 |
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 严禁使用 MD5、RC4 等弱算法； 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 对账文件加解密（可选）
平台产生的对账文件，采用对方的公钥进行加密，加密算法与上述一致；商户需使用商户私钥进行解密，以保证对账文件的完整性和安全性。
