商户签约API
接口介绍
该接口用于开立一网通帐户及签约,一网通帐户包括II类户、III类户,签约包括一网通支付、一网通免密支付、系统代发等。
约束条件
1. 申请合作方编码
2. 商户配置
3. 合作方保存协议号agrNo,并保证其唯一性。
请求地址
见开发指南
请求报文
报文的参数名:jsonRequestData,参数值JSON格式见下表
参数名称 | 参数名称 | 参数名称 | JSON键值 | 类型(长度) | 必填 | 描述 | 示例 |
---|---|---|---|---|---|---|---|
接口版本号 | version | String(3) | M | 固定为”2.0” | 2 | ||
参数编码 | charset | String(8) | M | 固定为“UTF-8” | UTF-8 | ||
报文签名 | sign | String | M | 使用商户密钥对reqData内的数据进行签名 | |||
签名算法 | signType | String | M | SHA-256或者NationalDigest | SHA-256 | ||
请求数据 | reqData | ||||||
请求时间 | dateTime | String(14) | M | 商户发起该请求的当前时间,精确到秒。 | 20160623101430 | ||
分行号 | branchNo | String(4) | M | 商户分行号,4位数字 | 755 | ||
商户号 | merchantNo | String(6) | M | 商户号,6位数字 | 123456 | ||
开户成功返回链接 | returnUrl | String(256) | O | 签约成功页面上“返回商户”按钮跳转地址, 默认值:http://CMBNPRM, 采用默认值的需要商户app拦截该请求, 自行决定跳转交互 | http://www.xxx.com/yyy | ||
开户失败返回链接 | FailreturnUrl | String(256) | O | 开户失败结果页上的按钮链接 | |||
首页返回链接 | hPageRtnLink | String(256) | M | 开户首页的返回按钮 | |||
扩展字段加密类型 | extendInfoEncrypType | String | M | AES或者NationalAES | |||
扩展字段加密后内容(敏感数据) | extendInfo | String | M | ||||
证件类型 | idtype | String(3) | O | 固定为”P01” | P01 | ||
证件号 | idno | String(18) | O | 身份证号 | 110000199501132885 | ||
姓名 | name | String | O | 用户姓名 | 小明 | ||
银行卡号 | accountno | String | O | 用户银行卡号 | 6216263233753265324 | ||
手机号 | mobile | String(11) | O | 用户银行卡预留手机号 | 15859160505 | ||
协议号 | agrNo | String(30) | M | 商户生成,必须为纯数字,且保证其唯一性 | 201606238888888 | ||
协议开通请求流水号 | merchantSerialNo | String(20) | M | 商户生成,同一交易日期唯一, 长度不超过20位,数字字母都可以, 建议纯数字 | 201606231014308 | ||
商户用户ID | userID | String(20) | O | 用于标识商户用户的唯一ID。 商户系统内用户唯一标识, 不超过20位,数字字母都可以, 建议纯数字 | |||
签约产品 | signprd | string | M | 签约产品ID列表,多个产品ID,用”| ”分隔。 PROD0001:一网通支付 PROD0002:一网通免密支付 PROD0003:系统代发 PROD0005:信用支付 PROD0006:信用闪付 RIGHT0001:滴滴联名权益 RIGHT0002:芒果联名权益 | PROD0001| PROD0002| RIGHT0001 | ||
经度 | lon | String(20) | O | 经度,商户app获取的手机定位数据 | 30.949505 | ||
纬度 | lat | String(20) | O | 纬度,商户app获取的手机定位数据 | 50.949506 | ||
风险等级 | riskLevel | String(4) | O | 用户在商户系统内风险等级标识 | |||
成功签约结果通知地址 | noticeUrl | String(256) | M | 商户接收成功签约结果通知的地址。 测试环境请传ip+端口(80/8081/443)的形式 生产环境ip加80/443端口, 或者用域名 | http://www.xxx.com/xxx | ||
成功签约结果通知附加参数 | noticePara | String(256) | O | 该参数在发送成功签约结果通知时, 将原样返回商户 注意:该参数可为空, 商户如果需要不止一个参数, 可以自行把参数组合、拼装, 但组合后的结果不能带有‘&’字符。 | |||
冻结金额 | money | string | O | 需要冻结的保证金金额 | 1000 | ||
解冻日期 | unfrozenDate | string | O | 解冻时间,精确到月份 | 20190203 | ||
备用字段 | unionId | String(15) | O | 招联Id | 招联商户专用, 请其他商户不要传值 | ||
备用字段 | GZUniversityCard | String(20) | O | 广州大学城一卡通号 | 广州大学城专用, 请其他商户不要传值 | ||
开户渠道 | chnType | O | 可为空 | ||||
网络接入方式 | networkAccess | O | 可为空 | ||||
IP | ip | O | 可为空 | ||||
APP版本 | appVersion | O | 可为空 | ||||
设备id | phyId | O | 可为空 | ||||
是否可信设备 | isTrustDevice | O | 可为空 | ||||
UA | userAgent | O | 可为空 | ||||
设备生产商 | mobileProducer | O | 可为空 | ||||
设备型号 | mobileModel | O | 可为空 | ||||
rom容量 | romVolume | O | 可为空 | ||||
ram容量 | ramVolume | O | 可为空 | ||||
cpu型号 | cpuModel | O | 可为空 | ||||
手机型号 | phoneNum | O | 可为空 | ||||
imsi | imsi | O | 可为空 | ||||
imeiIdfa | imeiIdfa | O | 可为空 | ||||
ssId | ssId | O | 可为空 | ||||
bssId | bssId | O | 可为空 | ||||
senInfor | senInfor | O | 可为空 |
请求示例
1、jsonRequestData字段内容
{ "version":"2.0", "charset":"UTF-8", "sign":"2A4CA8B5D18766BD739E02B551A0D4D5B694047C287DA33B4BC37FFB46A79772", "signType":"SHA-256", "reqData": { "dateTime":"20200813153902", "branchNo":"0021", "merchantNo":"000574", "returnUrl":"http://m.cmbchina.com/app2/index.html?source=ykx002bd", "failReturnUrl":"http://m.cmbchina.com/app2/index.html?source=ykx002bd", "extendInfoEncrypType":"AES", "extendInfo":"3I7jFzMz3knbjeJDu/XMeICI7OrOFfHaiq7OYRehO231GqxieJwLXPkMjMCYKqBOjDFIikkjQu0QnsX++EVt+pgvoSTDPKy59QM/mwbNjTKjg+ezWeyg9lyL0coRnpQpouSHz6eH7gsjIgaUUovqn05/3PfXorKU2kERbbdMRbx5r8NbONPhJ29dqTEU5eaFY1bJ0/CnP/zpR6kqqCJ55Xggav45B3DEyr6USEVqgIXyh97jLttk4JoaLtU9yvf4DnHwF/xJqSSsF3SMD5H/4UOGDC1tRcFPEqQR+JlyujCwkNIKvYKZ17iqvcqIqZX95QWLBjobccIV5MhZgO9Wt6IlcQsndtK0FCQKLLTVfkVNfj5zi4SfTlv2+1unHV41GrGv/UWkiSt84kGiFPZqC2BidvC21ciTjOK5nJqDFJKeikwfohE5T///Y8v0N3iLB8NGkTSwrXwvC5iHgeFPUA==", "chnType":"", "networkAccess":"", "ip":"", "appVersion":"", "phyId":"", "isTrustDevice":"", "userAgent":"", "mobileProducer":"", "mobileModel":"", "romVolume":"", "ramVolume":"", "cpuModel":"", "phoneNum":"", "imsi":"", "imeiIdfa":"", "ssId":"", "bssId":"", "senInfor":null, "hPageRtnLink":"http://m.cmbchina.com/app2/index.html?source=ykx002bd" } }
2、extendInfo字段说明
extendInfo 根据extendInfoEncrypType的加密类型,支持AES和NationalAES(国密),用商户配置的秘钥进行对称加密后的结果
3、sign字段说明
sign 根据signType的加签方式,支持SHA-256和NationalDigest(国密),对reqData字段内容进行排序后得到排序结果
appVersion=&branchNo=0021&bssId=&chnType=&cpuModel=&dateTime=20200813153902&extendInfo=3I7jFzMz3knbjeJDu/XMeICI7OrOFfHaiq7OYRehO231GqxieJwLXPkMjMCYKqBOjDFIikkjQu0QnsX++EVt+pgvoSTDPKy59QM/mwbNjTKjg+ezWeyg9lyL0coRnpQpouSHz6eH7gsjIgaUUovqn05/3PfXorKU2kERbbdMRbx5r8NbONPhJ29dqTEU5eaFY1bJ0/CnP/zpR6kqqCJ55Xggav45B3DEyr6USEVqgIXyh97jLttk4JoaLtU9yvf4DnHwF/xJqSSsF3SMD5H/4UOGDC1tRcFPEqQR+JlyujCwkNIKvYKZ17iqvcqIqZX95QWLBjobccIV5MhZgO9Wt6IlcQsndtK0FCQKLLTVfkVNfj5zi4SfTlv2+1unHV41GrGv/UWkiSt84kGiFPZqC2BidvC21ciTjOK5nJqDFJKeikwfohE5T///Y8v0N3iLB8NGkTSwrXwvC5iHgeFPUA==&extendInfoEncrypType=AES&failReturnUrl=http://m.cmbchina.com/app2/index.html?source=ykx002bd&hPageRtnLink=http://m.cmbchina.com/app2/index.html?source=ykx002bd&imeiIdfa=&imsi=&ip=&isTrustDevice=&merchantNo=000574&mobileModel=&mobileProducer=&networkAccess=&phoneNum=&phyId=&ramVolume=&returnUrl=http://m.cmbchina.com/app2/index.html?source=ykx002bd&romVolume=&ssId=&userAgent=
再拼接上 “&”+ 商户配置的秘钥,对组合成的结果字段串进行加签算法后得到sign字段
排序方法
public static string SortParams<T>(Object obj) { PropertyInfo[] pis = obj.GetType().GetProperties(); Array.Sort(pis, new PropertyInfoComparer()); StringBuilder sb = new StringBuilder(); int i = 0; foreach (PropertyInfo pi in pis) { if (pi.GetValue(obj, null) != null) { if (i == 0) { sb.Append(pi.Name + "=" + pi.GetValue(obj, null)); i++; } else { sb.Append("&" + pi.Name + "=" + pi.GetValue(obj, null)); } } } return sb.ToString(); }
排序后的内容加上秘钥,再生成sign字段
public static string GenerateSign<T>(Object reqdata, string signType, string password) { string sortStr = SortParams<T>(reqdata); sortStr = sortStr + "&" + password; if (signType == "SHA-256") { //HASH return HashSHA256.HashSHA256Hex(sortStr); } else if (signType == "NationalDigest") { //国密 return NationalCipher.Digest(sortStr); } else { throw new Exception("Error signType " + signType); } }
错误码
错误描述 | 解决方案 |
---|---|
参数长度无效,请重新进入 | 项目合作编码不能超过60位 |
数据异常#0 | url中必须传项目合作编码 |
数据异常#1 | 传输数据反序列化失败 |
数据异常##1 | 1. version必须为1.0 2. charset必须为UTF-8 3. sign必传 4. signType必须为SHA-256 |
数据异常##2 | 时间戳时间相差超过10分钟 |
数据异常##3 | 1. merchantSerialNo必传,长度不能超过20 2. agrNo必传,长度不能超过30 3. branchNo必传,长度不能超过4 4. merchantNo必传,长度不能超过6 5. signprd必传 6. noticeUrl必传,长度不能超过100 |
数据异常##33 | 1. merchantSerialNo支持 数字、大小写英文字母 2. agrNo支持数字 3. branchNo支持数字 4. merchantNo支持数字 |
数据异常##4 | 以下字段均非必传字段,若传了请满足以下: 1. idtype=P01 2. idno满足身份证格式 3. mobile满足手机号格式 4. accountno满足卡号格式 5. lon长度不能超过10 6. lat长度不能超过10 7. userId支持数字大小写英文字母,长度不能超过20 8. riskLevel长度不能超过3 9. noticePara长度不能超过128 10. returnUrl长度不能超过256 11. name长度不能超过60 12. chnType长度不能超过2 13. networkAccess长度不能超过4 14. ip满足ip格式 15. appVersion长度不能超过10 16. phyId长度不能超过64 17. isTrustDevice长度不能超过1 18. userAgent长度不能超过256 19. mobileProducer长度不能超过64 20. mobileModel长度不能超过64 21. romVolume长度不能超过16 22. ramVolume长度不能超过16 23. cpuModel长度不能超过64 24. phoneNum满足手机号格式 25. imsi长度不能超过32 26. imeiIdfa长度不能超过64 27. ssId长度不能超过40 28. bssId长度不能超过40 |
数据异常##5 | name和idno要么全为空,要么全不为空 |
数据异常###6 | 商户没有在招行配置商户号及密钥,请联系招行一网通支持小组 |
数据异常###7 | 签名有误:对字段进行排序生成待加密字符串+&MerKey,然后SHA-256加密比对sign。 |
数据异常##8 | unionId非必传字段,若传了长度必须为15 |
数据异常##9 | GZUniversityCard非必传字段,若传了长度不能超过20 |
签约包缺失返回链接 | 若传了EacFlag、EacTag,returnUrl必传 |
Q&A
Q1. 联调环境姓名、身份证、银行卡、手机号如何生成?
姓名随便写,身份证符合身份证规范即可,银行卡请使用621626开头的19位卡,手机号符合手机号规范即可。若还有疑问或碰到问题,请联系招行一网通支持小组。
Q2. 联调环境如何接收短信验证码?
请访问该地址查询:http://121.15.180.69/getmsgverifycode/default.aspx
Q3. 联调环境如何知道签约包是否传递成功?
因为开户接口支持带签约包和不带签约包两种模式,所以测试的时候可以在签约包里带上身份证、姓名、卡号、手机号,若签约包传递成功,该数据会回显。注:身份证、姓名要成对设置,卡号、手机号要成对设置。
Q4. 联调环境为什么一直报数据异常###7?
首先检查签名是否有误:对字段进行排序生成待加密字符串+&MerKey,然后SHA-256加密比对sign。如果没问题,那有可能是编码问题。以下是测试代码,可以将签约包放进input的value里进行测试。
<!DOCTYPE html> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> </head> <body class="ui-app"> <form id='myForm' action="http://paytest.cmbchina.com/IGateway/Jump.aspx?funcid=2006007&CorperationCode=xxxxx" method="post"> <input type="hidden" name="jsonRequestData" value='{ "version": "1.0", "charset": "UTF-8", "sign": "33a527f8dd2216cafed7407340f2d40c6c66ff448c64b7320d29bbc606b8769a", "signType": "SHA-256", "reqData": { "dateTime": "20180510094502", "merchantSerialNo": "2018050916500001", "agrNo": "", "branchNo": "0021", "merchantNo": "000333", "idno": "445381199408020454", "name": "陈嘉诚", "userID": "5961", "signprd": "PROD0001|PROD0002|PROD0003", "noticeUrl": "http://www.gzekt.com", "returnUrl": "http://www.baidu.com", "GZUniversityCard": "5961" } }'/> </form> </body> </html> <script type="text/javascript"> window.onload = function () { document.getElementById('myForm').submit(); } </script>
Q5. 银行卡手机号页面为什么要填是否其他税收居民的信息?
受监管要求,所有新开立的户口都需要填写是否其他税收居民的信息。若该客户已经在招商银行系统已经录入过该信息则不会展示此选项,否则展示此选项。此时如果客户选择是其他税收居民,则无法在线上办理一网通帐户。
Q6. 联调环境身份证、姓名页为什么经常报错:身份证姓名不一致等?
因为此处进行联网核查,测试环境是随机返回结果,故会随机报错或者成功,可多尝试几遍。若尝试多次仍然报错,请联系一网通支持小组成员。注:多次尝试的时候,请不要太频繁,10分钟最多20次。
Q7. 联调环境银行卡、手机号页为什么经常通过不了?
请联系一网通支持小组成员 。
Q8. 联调环境开户过程中为什么没有上传证件?
访问的时候没有使用固定的项目合作编码Z00001NG0120171010DZJKKWXSY000。但此项目合作编码不能带上生产,请联系分行业务人员帮忙申请各自的项目合作编码。生产上上传证件后,需要经过人工审核,客户才能进行提现,支付等操作。
Q9. 联调环境上传证件时经常卡住?
联调环境对照片有2M的大小限制,可选择从相册选择小一点的图片,生产上没有该种问题。
Q10. 生产上配置了对应的项目合作编码,为什么部分客户不用上传证件?
有些客户之前在招商银行留存过照片且有效,则开户过程中不会引导客户上传证件。可直接提现以及支付。
Q11. 若生产上用错了项目合作编码,客户没有上传证件,该如何处理?
请客户下载招商银行APP,从我的-银行卡-一网通帐户-帐户资料-身份认证 进入,上传身份证。其他客户在html上传过证件的也可在此路径下看到他人工审核的结果。
Q12. 生产环境提示客户已经有I理财帐户,无须办理一网通帐户?
请客户先下载招商银行APP,从全部-办卡开户-一网通帐户 进入 ,会引导客户将I理财帐户升级成一网通帐户。然后请客户再回到商户的APP进行签约操作。
Q13. 提示签约次数超限?
每个客户只能签两条不同的协议号,请联系一网通支持小组。一网通支持小组请联系刘铸文、程晓东。
Q14. 测试环境为何收不到回调通知?
测试环境需使用IP+端口的形式,端口支持80、8081、443端口。若还有疑问请联系一网通支持小组。
Q15. 生产环境为何收不到回调通知?
生产环境需使用IP+端口的形式,端口支持80、443端口,或者使用域名。若还有疑问请联系一网通支持小组。
Q16. 为什么结果页上提示核验超时?
从短信验证码页开始到结果页需小于3分钟。若对此时间限制有疑问,请联系业务人员。
Q17 为什么银行卡页会报DDIO1060-绑定手机与在招行预留的个人手机不一致?
若该客户在招行有预留手机号,必须填招行预留手机号,若没有,则必须与他行卡预留手机号一致。
Q18 生产商户密钥如何申请?
申请指南:http://121.15.180.72/openapi2/DOC/SrvTip9.aspx
1. 设置密钥链接地址 https://ebank.sz1.cmbchina.com/EB10/EBServer?Command=5001&ClientID=0&PRID=LOGINPREVIEW
2. 输入预登录密码75268
3. 选择开户分行、商户号填写六位数的商户号,操作员号9999,登录类型选择系统管理员登录,登录密码是六位数的商户号,点击登录首次登录需要修改登录密码
注:
1. 要用Windows系统
2. 要用IE内核浏览器,建议360浏览器
3. 如果是64位电脑,请打开兼容性视图
4. 如果以上都做了,但还是不显示预登陆密码框,请手动下载控件,地址:http://site.cmbchina.com/download/SafeEditInstall.exe,安装后,关掉所有浏览器窗口,重新打开
5. 不支持win10系统和mac电脑,请在其他系统电脑打开
Q19 生产环境报您的一网通不是手机号注册的
招商银行手机银行-我的-设置-点名字-登录手机号
Q20 为何需要加验银行卡?
根据监管要求,开通II类户的银行卡必须为I类户或信用卡,由于部分银行无法告知其银行卡属性,所以需要加验银行卡。
1. 若有本行储蓄卡,则显示本行储蓄卡供客户选择,需要客户验证取款密码。若取款密码输入有误,可切换其他加验方式 。
2. 若无本行储蓄卡,有本行信用卡,则显示本行信用卡供客户选择,需要客户验证查询密码。若查询密码输入有误,可切换其他加验方式。
3. 若无本行储蓄卡,也无本行信用卡,则请客户填写他行信用卡。
4. 若客户无他行信用卡,则根据是否支持降级III类户开关来决定是否开通降III类户。若不支持,则流程中断。