一网通账户

商户签约API

接口介绍

该接口用于开立一网通帐户及签约,一网通帐户包括II类户、III类户,签约包括一网通支付、一网通免密支付、系统代发等。


约束条件

1. 申请合作方编码

2. 商户配置

3. 合作方保存协议号agrNo,并保证其唯一性。


请求地址

见开发指南


请求报文

报文的参数名:jsonRequestData,参数值JSON格式见下表

参数名称参数名称参数名称JSON键值类型(长度)必填描述示例
接口版本号

versionString(3)M固定为”2.0”2
参数编码

charsetString(8)M固定为“UTF-8”UTF-8
报文签名

signStringM使用商户密钥对reqData内的数据进行签名
签名算法

signTypeStringMSHA-256或者NationalDigestSHA-256
请求数据

reqData




请求时间
dateTimeString(14)M商户发起该请求的当前时间,精确到秒。20160623101430

分行号
branchNoString(4)M商户分行号,4位数字755

商户号
merchantNoString(6)M商户号,6位数字123456

开户成功返回链接
returnUrlString(256)O签约成功页面上“返回商户”按钮跳转地址,
默认值:http://CMBNPRM,
采用默认值的需要商户app拦截该请求,
自行决定跳转交互
http://www.xxx.com/yyy

开户失败返回链接
FailreturnUrlString(256)O开户失败结果页上的按钮链接

首页返回链接
hPageRtnLinkString(256)M开户首页的返回按钮

扩展字段加密类型
extendInfoEncrypTypeStringMAES或者NationalAES

扩展字段加密后内容(敏感数据)
extendInfoStringM



证件类型idtypeString(3)O固定为”P01”P01


证件号idnoString(18)O身份证号110000199501132885


姓名nameStringO用户姓名小明


银行卡号accountnoStringO用户银行卡号6216263233753265324


手机号mobileString(11)O用户银行卡预留手机号15859160505


协议号agrNoString(30)M商户生成,必须为纯数字,且保证其唯一性201606238888888


协议开通请求流水号merchantSerialNoString(20)M商户生成,同一交易日期唯一,
长度不超过20位,数字字母都可以,
建议纯数字
201606231014308


商户用户IDuserIDString(20)O用于标识商户用户的唯一ID。
商户系统内用户唯一标识,
不超过20位,数字字母都可以,
建议纯数字



签约产品signprdstringM签约产品ID列表,多个产品ID,用”| ”分隔。
PROD0001:一网通支付
PROD0002:一网通免密支付
PROD0003:系统代发
PROD0005:信用支付
PROD0006:信用闪付
RIGHT0001:滴滴联名权益
RIGHT0002:芒果联名权益
PROD0001| PROD0002| RIGHT0001


经度lonString(20)O经度,商户app获取的手机定位数据30.949505


纬度latString(20)O纬度,商户app获取的手机定位数据50.949506


风险等级riskLevelString(4)O用户在商户系统内风险等级标识


成功签约结果通知地址noticeUrlString(256)M商户接收成功签约结果通知的地址。
测试环境请传ip+端口(80/8081/443)的形式
生产环境ip加80/443端口,
或者用域名
http://www.xxx.com/xxx


成功签约结果通知附加参数noticeParaString(256)O该参数在发送成功签约结果通知时,
将原样返回商户
注意:该参数可为空,
商户如果需要不止一个参数,
可以自行把参数组合、拼装,
但组合后的结果不能带有‘&’字符。



冻结金额moneystringO需要冻结的保证金金额1000


解冻日期unfrozenDatestringO解冻时间,精确到月份20190203


备用字段unionIdString(15)O招联Id招联商户专用,
请其他商户不要传值


备用字段GZUniversityCardString(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位
数据异常#0url中必须传项目合作编码
数据异常#1传输数据反序列化失败
数据异常##11. version必须为1.0
2. charset必须为UTF-8
3. sign必传
4. signType必须为SHA-256
数据异常##2时间戳时间相差超过10分钟
数据异常##31. merchantSerialNo必传,长度不能超过20
2. agrNo必传,长度不能超过30
3. branchNo必传,长度不能超过4
4. merchantNo必传,长度不能超过6
5. signprd必传
6. noticeUrl必传,长度不能超过100
数据异常##331. 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
数据异常##5name和idno要么全为空,要么全不为空
数据异常###6商户没有在招行配置商户号及密钥,请联系招行一网通支持小组
数据异常###7签名有误:对字段进行排序生成待加密字符串+&MerKey,然后SHA-256加密比对sign。
数据异常##8unionId非必传字段,若传了长度必须为15
数据异常##9GZUniversityCard非必传字段,若传了长度不能超过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类户。若不支持,则流程中断。