报文数据说明

数据类型

String(x)表示最大长度为x字节的变长字符串,如有固定长度等特殊要求在接口文档中说明。
String表示长度不做限制的变长字符串
长度的计算说明:所有长度均按字节计算,中文算两个字节,英文、数字算一个字节。

参数值是否必填约定

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

签名

首先,组成待签名字符串。待签名字符串组成规则为:对待验签的所有请求参数按从a到z的字典顺序排列,如果首字母相同,按第二个字母排列,以此类推。排序完成后按将所有键值对以“&”符号拼接,拼接完成的待签名字符串格式如下:
param1=value1&param2=value2&……
其次,将商户签名密钥增加“&”附加到待签名字符串后,按指定签名算法进行运算。假设待签名字符串为strToSign,商户密钥为merkey,算法为sha256,对strToSign&merkey进行sha256签名运算获得签名结果byte数组,将byte数组转换为16进制即为最终的签名结果。
注意:
  1. 所有reqData(或rspData)参数,即便其值为空,也要加入到待签名字符串;
  2. 注意排序时按字典顺序排序,字母顺序与大小写无关。例如:sDate与sdateTime的顺序是sDate=XXX&sdateTime=XXX,sdate与sDateTime的顺序是sdate=XXX&sDateTime=XXX;
  3. 签名时,按指定的字符集将字符串转换为字节流;
  4. 根据HTTP协议要求,如果请求参数值中有特殊字符和汉字,如&、@等,需进行URLEncoding处理。待签名数据为原生值而非encoding后的值。如:参数值为email=test@msn.com,则签名值是email=test@msn.com,而非email=test%40msn.com

报文样例:

{
  "version":"1.0",
  "charset":"UTF-8",
  "sign":"见签名处理章节",
  "signType":"ABCDAEEDDDFA",
  "reqData":{                   
       "param1":"value1",
       "param2":"value2",
       "dateTime":"20161024182921",
       }
 }

待签名字符串(不包含支付密钥)为:
dateTime=20161024182921&param1=value1&param2=value2
(注意:为了支持参数扩展,商户必须使用算法对待签名参数进行排序,不能使用程序写死的方法硬拼接参数顺序。)

验签

(用于对“成功支付结果通知”接收到的通知报文进行验签)
首先,组成待签名字符串。待签名字符串组成规则为:对noticeData所有参数名转换为小写后按从a到z的字典顺序排列,如果首字母相同,按第二个字母排列,以此类推。排序完成后按将所有键值对以“&”符号拼接,拼接完成的待签名字符串格式如下:
param1=value1&param2=value2&……
其次,使用招行公钥进行验签。假设待签名字符串为strToSign,招行通知公钥为publicKey, 签名内容为strSign,算法为标准的RSA算法,加密算法为SHA1WithRSA,对strToSign进行签名校验。
招行通知公钥可以通过调用“查询招行公钥”接口获取,详见查询招行公钥API介绍。
银行系统会对支付结果异步通知报文进行签名,商户需对报文签名进行验签。这里的公钥用于生产环境支付结果异步通知报文验签,商户可根据自身情况将公钥存放在合适地方。

【测试环境企业网银公钥】
目前,联调测试环境下的企业网银公钥如下:
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDZs4l8Ez3F4MG0kF7RRSL+pn8MmxVE3nfdXzjx6d3rH8IfDbNvNRLS0X0b5iJnPyFO8sbbUo1Im4zX0M8XA0xnnviGyn5E6occiyUXJRgokphWb5BwaYdVhnLldctdimHoJTk3NFEQFav3guygR54i3tymrDc8lWtuG8EczVu8FwIDAQAB

【生产环境企业网银公钥】
目前,生产环境下的企业网银公钥如下:
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCyrJLW4e4/TvaTNKe6p8cSJoDg6sY6Yk+15dm72QssCbcLDSOgnIagGoDmBiYxtDWbJ4xbp08OWDPUw+SsbFDiCwC+iGjTB/31kRIVY5FAyeAmLS1pSqMxJb10adYmcX+ushx4TeLe0xOUvTVqRAUp9+0xHxS1PfRqNVkXiNVzdQIDAQAB

注意:
1. 所有noticeData中请求参数,即便其值为空,也加入签名字符串;
2. 验签字符串不需要拼接招行公钥;
3. 注意排序时按字典顺序排序,字母顺序与大小写无关。例如:sDate与sdateTime的顺序是sDate=XXX&sdateTime=XXX,sdate与sDateTime的顺序是sdate=XXX&sDateTime=XXX;
4. 签名时,按指定的字符集将字符串转换为字节流。
5. 根据HTTP协议要求,如果请求参数值中有特殊字符,如&、@等,需进行URLEncoding处理。待签名数据为原生值而非encoding后的值。如:参数值为email=test@msn.com,则签名值是email=test@msn.com,而非email=test%40msn.com。

报文样例:

{
  "version":"1.0",
  "charset":"UTF-8",
  "sign":"签名结果(strSign)",
  "signType":"RSA",
  "noticeData":{                   
       "dateTime":"20161024182921",
       "noticeUrl":"https://...",
       "httpMethod":"POST",
       "branchNo":"0755",
       "merchantNo":"002346",
       "noticeType":"BKPAY",
       "noticeSerialNo":"201610248888888",
       "param1":"aaa",
       "param2":"bbb",
       }
 }

待验证签名字符串strToSign为:
branchNo=0755&dateTime=20161024182921&httpMethod=POST&merchantNo=002346&noticeSerialNo=201610248888888&noticeType=BKPAY&noticeUrl=https://...&param1=aaa&param2=bbb
注:验签代码示例,请参见:附录

FAQ

Q1. 为什么我在做测试时,招行系统显示 “签名验证失败”?

验签失败,sign内容不正确。

可能原因:

1、 签名时使用的商户支付密钥与设置的不一样,请确认支付密钥配置与环境是否匹配;

2、 生成签名数据时填写的参数与支付接口中填写的相应参数不一样;

3、 生成签名数据的参数排序顺序不正确,请仔细核对文档中的排序顺序;

4、 特殊字符是否加密正确,例如服务器端&字符是否被转换为&,导致签名错误;

5、 参数前后是否包含空格,请不要包括空格;

6、 可选参数其值为空串,对应的参数名称未拼接到待签名字符串中。

关于网站迁移公告


为提供更优质的开发技术支持,本网站已于2019年8月12日正式迁移至新域名http://openhome.cmbchina.com/paynew/pay/Home,敬请访问并收藏。原网站域名已停止更新维护,请以新网站提供的文档信息为准。

由此给您带来的不便,敬请谅解。


招商银行一网通支付技术支持小组

2019年8月12日