一网通账户

商户签约API

开户及签约:

  • 接口介绍:

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


  • 约束条件:

  (1) 申请合作方编码

  (2) 商户配置

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


  • 请求地址:

  见 开发指南->开发测试环境

输入参数

  • MODEL: jsonRequestData

参数类型必须字段说明描述示例
versionString(3)M接口版本号固定为”2.0”2
charsetString(8)M参数编码固定为“UTF-8”UTF-8
signStringM报文签名使用商户密钥对reqData内的数据进行签名
signTypeStringM签名算法NationalDigestNationalDigest
reqData

请求数据

sign字段签名算法说明如下:

首先组成待签名字符串。待签名字符串组成规则为:对待验签的所有请求数据(reqData中所有字段)按从a到z的字典顺序排列,如果首字母相同,按第二个字母排列,以此类推。排序完成后按将所有键值对以“&”符号拼接:

param1=value1&param2=value2&……

将商户签名密钥增加“&”附加到待签名字符串后,按指定签名算法进行运算。假设待签名字符串为strToSign,商户密钥为merkey,算法为sm3,对strToSign&merkey进行SM3签名运算获得签名结果byte数组,将byte数组Base64.toBase64String输出


  • MODEL: reqData   必填为M时表示必传,O表示可不传

参数类型必填说明描述示例
dateTimeString(14)M请求时间商户发起该请求的当前时间,精确到秒。20160623101430
branchNoString(4)M分行号商户分行号,4位数字755
merchantNoString(6)M商户号商户号,6位数字123456
returnUrlString(256)O开户成功返回链接开户签约成功页面上“返回”按钮跳转地址,默认是商管配置的成功结果页链接

签约包和商管配置中都为空时,

站内默认为回到首页,站外默认为:https://m.cmbchina.com/app2/index.html

failReturnUrlString(256)O开户失败返回链接开户失败结果页上的按钮链接,默认是商管配置的失败结果页链接

签约包和商管配置中都为空时,

站内默认为回到首页,站外默认为:https://m.cmbchina.com/app2/index.html

hPageRtnLinkString(256)O首页返回链接

首页的左上角返回链接,不能传functionjump这样的链接,必须是完整的可直接访问的链接 ,不然就传空或不传。

类似 http://www.baidu.com 这种
returnTypeString(256)O返回类型

仅支持站外开户成功后跳转跳钱包总览页。站内开户不接收该字段

可与hideSucResultPage配合使用,hideSucResultPage=Y,returnType=AccountView表示开户成功后不展示成功页直接跳转钱包总览

hideSucResultPage=Y,returnType=TransIn表示开户成功后不展示成功页直接跳转充值首页

returnType=AccountView/TransIn,hideSucResultPage为N或空,表示开户成功后展示成功结果页,完成按钮跳转钱包总览或充值首页

hideSucResultPage=Y时returnType和openSucReturnUrl只能一个传值,优先级returnType>openSucReturnUrl


1-开户后跳转总览或充值

仅站外

AccountView 或

TransIn


rtnLinkString(256)O资金转入结果页返回链接资金转入结果页的返回链接,当ReturnType为TransIn时需输入,非必输
hideSucResultPageString(1)O是否隐藏开户成功结果页Y隐藏  不传默认展示开户成功页。适用于开户完成后直接回到之前流程的场景。默认为空

2-开户后直接跳

转指定链接

openSucReturnUrlString(256)O开户成功跳转链接hideSucResultPage为Y时需传,开户成功后直接跳回该地址,如果为空,则展示开户成功页。默认为空
brnNbrString(6)O开户机构号开户机构号, 6位数字,非必输
psbCodString(4)O凭证种类凭证种类,长度4位,非必输

extendInfoEncrypType

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

  • MODEL: extendInfo

extendInfo 字段说明:

需加密的数据,加密算法为SM4


参数类型必填说明描述示例
merchantSerialNoString(20)M协议开通请求流水号商户生成,同交易日期唯
长度不超过20位,数字字母都可以,
建议纯数字
201606231014308
agrNoString(30)M协议号商户生成,必须为纯数字,且保证其唯201606238888888
idtypeString(3)O证件类型固定为”P01”P01
idnoString(18)O证件号身份证号110000199501132885
nameStringO姓名用户姓名小明
accountnoStringO银行卡号用户银行卡号6216263233753265324
mobileString(11)O手机号用户银行卡预留手机号15859160505

frontImage

String

O证件影像国徽面

 base64字符串,大小不能超过500K,如传证件影像,必须使用post方式传参。仅站外签约包开户支持。


backImage

String

O证件影像人像面 base64字符串,大小不能超过500K,如传证件影像,必须使用post方式传参。仅站外签约包开户支持

userAddress

String(50)

O地址地址

userJob

String(4)

O职业编码

新国标职业编码


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

signprdstringO签约产品

如商管配置需要签支付或免密的约,该字段必送

签约产品ID列表,多个产品ID,用”| ”分隔。

PROD0001:一网通支付
PROD0002:一网通免密支付
PROD0003:系统代发
PROD0005:信用支付
PROD0006:信用闪付
RIGHT0001:滴滴联名权益
RIGHT0002:芒果联名权益
WLT:联名账户
WLT
lonString(20)O经度经度,商户app获取的手机定位数据30.949505
latString(20)O纬度纬度,商户app获取的手机定位数据50.949506
riskLevelString(4)O风险等级用户在商户系统内风险等级标识
noticeUrlString(256)O成功签约结果通知地址商户接收成功签约结果通知的地址。
测试环境请传ip+端口(80/8081/443)的形式
生产环境ip加80/443端口,
或者用域名
http://www.xxx.com/xxx
noticeParaString(256)O成功签约结果通知附加参数该参数在发送成功签约结果通知时,
将原样返回商户
注意:该参数可为空,
商户如果需要不止个参数,
可以自行把参数组合、拼装,
但组合后的结果不能带有‘&’字符。

faceSerialNostringO人脸流水商管中配置支持商户自处理活体采集且商户采集了人脸的需要传人脸流水
GZUniversityCardString(20)O备用字段广州大学城卡通号广州大学城专用,
请其他商户不要传值
sucToTransInString(1)O开户成功跳转充值开户成功后直接跳转充值,传Y。用于开户后直接充值场景,如果不是该场景不传3-开户后跳转充值
transamtStringO交易金额充值金额,11位整数2位小数的格式。仅sucToTransIn为Y是有效
hideTransInHomeString(1)O是否隐藏充值首页开户后跳充值是否隐藏充值首页(站外表示展示充值首页自动提交充值拉起密码框,因站外不能省去验密环节),传Y表示隐藏,传N表示不隐藏。当交易金额为空时,该值必须为N,仅sucToTransIn为Y是有效,默认不隐藏。
hideTransInResultString(1)O是否隐藏充值结果页开户后跳充值是否隐藏充值成功结果页,传Y表示隐藏,传N表示不隐藏。仅sucToTransIn为Y是有效,默认不隐藏。
transSerialNoStringO交易流水号商户端提供的交易流水,充值时透传给主机,用于商户查询充值结果,不能重复。仅sucToTransIn为Y是有效,当hideTransInResult为Y时必输。
transInSucUrlString(256)O充值成功返回链接开户充值成功后,隐藏充值结果页的前提下,直接跳回商户的链接;如不隐藏充值结果页,成功结果页的返回按钮链接。仅sucToTransIn为Y是有效,hideTransInResult为Y时必输
transInFailUrlString(256)O充值失败返回链接开户充值过程中开户或充值失败或未知页的返回按钮的链接,或充值首页左上角返回链接。仅sucToTransIn为Y是有效,为空时开户结果页为商管配置中的链接,充值失败或未知页为关闭当前页,充值首页左上角不设置。


注意事项

1、开户后的跳转方式1(开户后跳转总览或充值(仅站外))、2(开户后直接跳转指定链接)、3(开户后跳转充值)互斥,只能存在一种方式跳转,优先级1>2>3

     方式1-开户后直接跳转钱包总览或充值,仅支持站外签约包开户,开户成功后展示结果页,在结果页点击完成按钮直接 跳转账户总览或充值,省去核身环节。可与hideSucResultPage配合使用,展示或不展示开户成功结果页 。

     方式2-开户后直接跳转指定链接,主要应用场景:其他业务跳转开户后不展示结果页直接返回该业务 

     方式3-开户后跳转充值,将开户和充值流程合并,开户后直接发起充值,不展示开户结果页。

2、开户充值合并流程中,当开户或充值失败时需返回商户特定地址,则返回链接failReturnUrl、首页返回链接hPageRtnLink、充值失败返回链接transInFailUrl三个地址都需要赋值


示例

extendInfo加密示例:

密钥:1234567890abcABC

明文:{\"signprd\": \"WLT\",\"noticeUrl\": \"http://www.baidu7598.com\",\"merchantSerialNo\": \"20210321154878\",\"agrNo\": \"29877687582358986099\"}

密文:vkfJq1b4cMVn/7oa9M5/MfciQvJDvizBCTrDIOSbhHhq7S+c/8vlqRMThV77QuLdnewnVfvnQPYIkUMdV9TN5H5VXC5uivmrw6LmiT/Q/UjFCQeB3+BBJm4p8Kf7k6NDGJM7nPkuBMGghneyGwhO0KSN1Uszcuja/VZ7pAolbXc=


完整报文示例:
{
 "reqData": {
   "dateTime": "20221109194914",
   "extendInfoEncrypType": "NationalAES",
   "failReturnUrl": "http://openhome.cmbchina.com",
   "hPageRtnLink": "http://openhome.cmbchina.com",
   "hideSucResultPage": "",
   "returnUrl": "http://openhome.cmbchina.com",
   "rtnLink": "http://openhome.cmbchina.com",
   "extendInfo": "vkfJq1b4cMVn/7oa9M5/MfciQvJDvizBCTrDIOSbhHhq7S+c/8vlqRMThV77QuLdnewnVfvnQPYIkUMdV9TN5H5VXC5uivmrw6LmiT/Q/UjFCQeB3+BBJm4p8Kf7k6NDGJM7nPkuBMGghneyGwhO0KSN1Uszcuja/VZ7pAolbXc=",
   "openSucReturnUrl": "",
   "returnType": "",
   "branchNo": "0571",
   "merchantNo": "022863"
 },
 "charset": "UTF-8",
 "sign": "NzC5fNx8QBqQsLs1Z199UJT/cybD7bUC6JY772Rim34=",
 "signType": "NationalDigest",
 "version": "2.0"
}

待签名字符串:
branchNo=0571&dateTime=20221109194914&extendInfo=vkfJq1b4cMVn/7oa9M5/MfciQvJDvizBCTrDIOSbhHhq7S+c/8vlqRMThV77QuLdnewnVfvnQPYIkUMdV9TN5H5VXC5uivmrw6LmiT/Q/UjFCQeB3+BBJm4p8Kf7k6NDGJM7nPkuBMGghneyGwhO0KSN1Uszcuja/VZ7pAolbXc=&extendInfoEncrypType=NationalAES&failReturnUrl=http://openhome.cmbchina.com&hideSucResultPage=&hPageRtnLink=http://openhome.cmbchina.com&merchantNo=022863&openSucReturnUrl=&returnType=&returnUrl=http://openhome.cmbchina.com&rtnLink=http://openhome.cmbchina.com&1234567890abcABC

签名:NzC5fNx8QBqQsLs1Z199UJT/cybD7bUC6JY772Rim34=

联调环境完整请求链接:
https://virtualjump.csst.cmburl.cn/zB8dMAAA?CorperationCode=Z00001000000000000000DKZCXZ&jsonRequestData=%7B%22reqData%22%3A%7B%22dateTime%22%3A%2220221109194914%22%2C%22extendInfoEncrypType%22%3A%22NationalAES%22%2C%22failReturnUrl%22%3A%22http%3A%2F%2Fopenhome.cmbchina.com%22%2C%22hPageRtnLink%22%3A%22http%3A%2F%2Fopenhome.cmbchina.com%22%2C%22hideSucResultPage%22%3A%22%22%2C%22returnUrl%22%3A%22http%3A%2F%2Fopenhome.cmbchina.com%22%2C%22rtnLink%22%3A%22http%3A%2F%2Fopenhome.cmbchina.com%22%2C%22extendInfo%22%3A%22vkfJq1b4cMVn%2F7oa9M5%2FMfciQvJDvizBCTrDIOSbhHhq7S%2Bc%2F8vlqRMThV77QuLdnewnVfvnQPYIkUMdV9TN5H5VXC5uivmrw6LmiT%2FQ%2FUjFCQeB3%2BBBJm4p8Kf7k6NDGJM7nPkuBMGghneyGwhO0KSN1Uszcuja%2FVZ7pAolbXc%3D%22%2C%22openSucReturnUrl%22%3A%22%22%2C%22returnType%22%3A%22%22%2C%22branchNo%22%3A%220571%22%2C%22merchantNo%22%3A%22022863%22%7D%2C%22charset%22%3A%22UTF-8%22%2C%22sign%22%3A%22NzC5fNx8QBqQsLs1Z199UJT%2FcybD7bUC6JY772Rim34%3D%22%2C%22signType%22%3A%22NationalDigest%22%2C%22version%22%3A%222.0%22%7D


生产环境
1、将链接中https://virtualjump.csst.cmburl.cn/zB8dMAAA  替换成 https://t.cmbchina.com/txB4JMAA
2、密钥改为生产密钥

输出参数

错误码

错误描述解决方案
参数长度无效,请重新进入项目合作编码不能超过60位
数据异常#0url中必须传项目合作编码
数据异常#1传输数据反序列化失败
数据异常##11. version必须为2.0
2. charset必须为UTF-8
3. sign必传
4. signType必须为NationalDigest
数据异常##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,然后SM3加密比对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类户。若不支持,则流程中断。