一网通支付API
若客户未安装手机银行则调取下方支付接口
请求地址
生产环境
https://netpay.cmbchina.com/netpayment/BaseHttp.dll?MB_EUserPay
测试环境
http://netpay.netpay.bas.cmburl.cn:801/netpayment/BaseHttp.dll?MB_EUserPay
请求报文
报文的参数名:jsonRequestData,参数值JSON格式见下表
参数 | 类型(长度) | 必填 | 描述 | 示例 |
version | String(3) | M | 接口版本号,固定为“1.0” | 1.0 |
charset | String(8) | M | 参数编码,固定为“UTF-8” | UTF-8 |
sign | String | M | 报文签名,使用支付密钥对reqData内的数据进行签名 | |
signType | String | M | 签名算法,固定为“SHA-256” | SHA-256 |
reqData | 请求数据 | |||
dateTime | String(14) | M | 请求时间,格式:yyyyMMddHHmmss 商户发起该请求的当前时间,精确到秒 | 20161209112230 |
branchNo | String(4) | M | 分行号,4位数字 | 0755 |
merchantNo | String(6) | M | 商户号,6位数字 | 000054 |
date | String(8) | M | 订单日期,格式:yyyyMMdd | 20161024 |
orderNo | String(32) | M | 订单号。 支持6-32位(含6和32)间任意位数的订单号,支持不固定位数,支持数字+字母(大小字母)随意组合。由商户生成,一天内不能重复。 订单日期+订单号唯一定位一笔订单。 | 9999000001 |
amount | String(14) | M | 订单金额,格式:xxxx.xx 固定两位小数,最大11位整数 | 0.01 |
expireTimeSpan | String(2) | M | 过期时间跨度,必须为大于零的整数,单位为分钟。该参数指定当前支付请求必须在指定时间跨度内完成(从系统收到支付请求开始计时),否则按过期处理。一般适用于航空客票等对交易完成时间敏感的支付请求。 | 1 |
payNoticeUrl | String(256) | M | 商户接收成功支付结果通知的地址。 | http://www.merchant.com/path/payNotice.do |
payNoticePara | String(256) | O | 成功支付结果通知附加参数,该参数在发送成功支付结果通知时,将原样返回商户注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。 | 12345678|ABCDEFG|HIJKLM |
returnUrl | String(256) | O | 返回商户地址,支付成功页面、支付失败页面上“返回商户”按钮跳转地址。如客户多次输入支付密码错误后提示“改日再试”按钮也会跳转该地址。 为空则不显示返回商户按钮。 原生APP可传入一个特定地址(例如:Http://CMBNPRM),并拦截处理自行决定跳转交互。 | http://www.merchant.com/path/return.do |
clientIP | String(64) | O | 商户取得的客户IP,如果有多个IP用逗号”,”分隔。 | 99.12.38.165 |
cardType | String(1) | O | 允许支付的卡类型,默认对支付卡种不做限制,储蓄卡和信用卡均可支付 A:储蓄卡支付,即禁止信用卡支付 | |
agrNo | String(32) | O | 客户协议号。如商户上送协议号,客户再次支付无需进行登录操作,推荐上送。 支持数字、字母(大小字母)、“-””_”两个特殊字符(注意-_是英文半角的)。 未签约(首次支付)客户,填写新协议号,用于协议开通; 已签约(再次支付)客户,填写该客户已有的协议号。商户必须对协议号进行管理,确保客户与协议号一一对应。 | 12345678901234567890 |
merchantSerialNo | String(30) | C | 协议开通请求流水号,开通协议时必填。 | 2016062014308888 |
userID | String(20) | O | 商户用户ID,用于标识商户用户的唯一ID。商户系统内用户唯一标识,不超过20位,数字字母都可以,建议纯数字 | 2016062388888 |
mobile | String(11) | O | 商户用户的手机号 | 18202532653 |
lon | String(10) | O | 经度,商户app获取的手机定位数据,如30.949505 | 30.949505 |
lat | String(10) | O | 纬度,商户app获取的手机定位数据,如50.949506 | 50.949506 |
riskLevel | String(4) | O | 风险等级,用户在商户系统内风险等级标识 | |
signNoticeUrl | String(100) | C | 成功签约结果通知地址,上送协议号且首次签约,必填。商户接收成功签约结果通知的地址。 | http://www.merchant.com/path/signNotice.do |
signNoticePara | String(128) | O | 成功签约结果通知附加参数,该参数在发送成功签约结果通知时,将原样返回商户 注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。 | 12345678|ABCDEFG|HIJKLM |
extendInfo | String | O | 扩展信息,json格式写入的扩展信息,并使用extendInfoEncrypType指定的算法加密使用详见扩展信息注意:1.加密后的密文必须转换为16进制字符串2.如果扩展信息字段非空,该字段必填 | |
extendInfoEncrypType | String | O | 扩展信息的加密算法,扩展信息加密类型,取值为RC4或DES 加密密钥: 取值为RC4时,密钥为商户支付密钥; 取值为DES时,密钥为商户支付密钥的前8位,不足8位则右补0 注意:如果扩展信息字段非空,该字段必填 |
请求示例
1. json报文组织:
{ "version":"1.0", "charset":"UTF-8", "sign":"见签名处理章节", "signType":"SHA-256", "reqData":{ "dateTime":"20161209112230", "branchNo":"0755", "merchantNo":"000054", "date":"20161209", "orderNo":"9999000001", "amount":"0.01", "expireTimeSpan":"30", "payNoticeUrl":"http://www.merchant.com/path/payNotice.do", "payNoticePara":"12345678|ABCDEFG|HIJKLM", "returnUrl":"http://www.merchant.com/path/return.do", "clientIP":"99.12.38.165", "cardType":"A", "agrNo":"12345678901234567890", "merchantSerialNo":"2016062014308888", "userID":"2016062388888", "mobile":"18202532653", "lon":"30.949505", "lat":"50.949506", "riskLevel":"", "signNoticeUrl":"http://www.merchant.com/path/signNotice.do", "signNoticePara":"12345678|ABCDEFG|HIJKLM", "extendInfo":"C7788996853803BB6981F406BA84939CE96B8D57FFB20B653078B181FA9691D7CFF00D1D3EF21E6B338A3FD33690CAF12078BE885BB49F6016CF5A0314D21BF49738629F8386CB437A76A8DBE1E7E932DBDB18B7C69A8D10900FB8A3C98CB48833B5800A541DD6B5A12F65508C3BCD1D51B32DD02CCE362BB5CE4D95E5D29921E603BBE3CA5B650652589011304CC2969E2A1046F91A1849B70001FE23EA8592560BE4FB7994D51BC7E7F5F5E08474F7090A44D635F2BFD7353B081DF80613817FD357CD472392A2EFEB1DA52D72DADD3BD5725FE42FA9D4B19", "extendInfoEncrypType":"RC4" } }
2. 表单组织:
<form action="请求地址" method="post" /> <input type="hidden" name="jsonRequestData" value='以上json字符串' /> <input type="hidden" name="charset" value='UTF-8' /> </form>
3. 待签名字符串(未包含支付密钥):
agrNo=12345678901234567890&amount=0.01&branchNo=0755&cardType=A&clientIP=99.12.38.165&date=20161209&dateTime=20161209112230&expireTimeSpan=30&extendInfo=FC7788996853803BB6981F406BA84939CE96B8D57FFB20B653078B181FA9691D7CFF00D1D3EF21E6B338A3FD33690CAF12078BE885BB49F6016CF5A0314D21BF49738629F8386CB437A76A8DBE1E7E932DBDB18B7C69A8D10900FB8A3C98CB48833B5800A541DD6B5A12F65508C3BCD1D51B32DD02CCE362BB5CE4D95E5D29921E603BBE3CA5B650652589011304CC2969E2A1046F91A1849B70001FE23EA8592560BE4FB7994D51BC7E7F5F5E08474F7090A44D635F2BFD7353B081DF80613817FD357CD472392A2EFEB1DA52D72DADD3BD5725FE42FA9D4B19&extendInfoEncrypType=RC4&lat=50.949506&lon=30.949505&merchantNo=000054&merchantSerialNo=20161209112230&mobile=18202532653&orderNo=9999000001&payNoticePara=12345678|ABCDEFG|HIJKLM&payNoticeUrl=http://www.merchant.com/path/WAPProcResult.dll&returnUrl=http://www.merchant.com/path/return.do&riskLevel=&signNoticePara=12345678|ABCDEFG|HIJKLM&signNoticeUrl=http://www.merchant.com/path/signNotice.do&userID=2016062388888
4. 扩展信息
扩展信息(extendInfo)用于商户上送一些订单信息、用户信息。 json格式写入扩展信息,并使用extendInfoEncrypType指定的算法加密
a)扩展信息字段可以传的参数
参数名称 | 说明 | 类型 | 长度 | 是否必填 | 示例值 |
userIDRegisterTime | 商户用户注册ID注册时间 | String | 26 | 可空 | 时间戳。格式2016-01-01 14:33:22 |
newRegisterFlag | 是否是24H内注册ID | String | 1 | 可空 | Y/N |
cityCode | 粗略地理位置 | String | 6 | 可空 | 使用行政区划代码,六位,如深圳为440300 |
addressCity | 订单收货城市 | String | 6 | 可空 | 使用行政区划代码,六位,如深圳为440300 |
addressMobile | 订单收货人手机号 | String | 11 | 可空 | 11位手机号或手机号未4位。 |
productType | 产品及服务标识 | String | 12 | 可空 | |
deviceOS | 操作系统类型 | String | 12 | 可空 | ANDROID 或 IOS |
deviceIMEI | IMEI | String | 32 | 可空 | ANDROID设备时上送 |
deviceIDFA | IDFA | String | 64 | 可空 | IOS设备时上送 |
1)扩展信息字段的使用说明
json格式写入扩展信息,并使用extendInfoEncrypType指定的算法加密。加密算法如下:
首先将需传入的风控参数拼接成json,再使用RC4或DES加密生成16进制的字符串即为extendInfo字段。extendInfoEncrypType取值为RC4时,密钥为商户支付密钥;取值为DES时,密钥为商户支付密钥的前8位,不足8位则右补0。RC4与DES算法参考附录中的RC4代码示例和DES代码示例。
b)加密结果的样例
加密前:
{"userIDRegisterTime":"2016-01-01 14:33:22","newRegisterFlag":"N","cityCode":"440300","addressCity":"440300","addressMobile":"15867147111","productType":"pt","deviceOS":"ANDROID","deviceIMEI":"IME","deviceIDFA":"IDFA"}
RC4加密后:
FC7788996853803BB6981F406BA84939CE96B8D57FFB20B653078B181FA9691D7CFF00D1D3EF21E6B338A3FD33690CAF12078BE885BB49F6016CF5A0314D21BF49738629F8386CB437A76A8DBE1E7E932DBDB18B7C69A8D10900FB8A3C98CB48833B5800A541DD6B5A12F65508C3BCD1D51B32DD02CCE362BB5CE4D95E5D29921E603BBE3CA5B650652589011304CC2969E2A1046F91A1849B70001FE23EA8592560BE4FB7994D51BC7E7F5F5E08474F7090A44D635F2BFD7353B081DF80613817FD357CD472392A2EFEB1DA52D72DADD3BD5725FE42FA9D4B19
DES加密后:
b03a08bbd94a3b21554325f8db18256f38a3cb7d158853c1318af38fbebe208f1795279acc58deed1003ee744dceb7d5554325f8db18256f40ab6a3753b8fc7a8a1b1a83f83dcf43327d026813dcbdca6a4c5448bc838f0d473757290e357c2702e3e12fe81f3ab8cac5790dd4434673e80b93e2924754225a08679ddbd5d22b67b0f76837f26f069242cd4c263fde614f732af955925b834333974835892a1b051eca9f5aef7cd4eb7abd6b6327d0aa03df934ced517aae870a4bccb99e8fc54a940557ed0e1d4670eee0c6da97829223d6aa182241e0500c2f7cafab0ab326
响应报文
网页直接展示结果,无响应报文。
签约成功和支付成功后有异步结果通知,失败无通知。
错误码
错误码 | 描述 | 解决方案 |
请求参数错误: | ||
NP1016 | 分行号格式错误 | 参数branchNo错误 商户开户分行号,4位数字,请咨询开户的招商银行分支机构; |
NP1017 | 商户号格式错误 | 参数merchantNo错误 商户号,6位数字,由银行在商户开户时确定;//收单商户号 |
NP1020 | 金额格式错误 | 参数amount错误 订单总金额,格式为:xxxx.xx元; |
NP1022 | 日期格式错误 | 参数dateTime或date错误 Date: yyyyMMdd,TS:yyyyMMddHHmmss |
NP1029 | 订单已过期:请回到商户网站,重新生成订单 | 参数dateTime错误 订单已过期,请求时间和当前系统时间间隔超过30分钟 |
NP1034 | 商户通知URL地址格式错误 | 参数payNoticeUrl错误 格式要求:“https://”或“http://”开头 |
NP1035 | 商户通知参数超长 | 参数payNoticePara或signNoticePara错误 参数长度超过128个字节 |
NP1070 | 商户附加信息中,包含不允许的内容 | 参数payNoticePara或signNoticePara错误 参数值不允许有脚本 |
NP1071 | 订单过期时间(分钟)格式错误 | 参数expireTimeSpan错误 必须为大于零的整数,单位为分钟。 |
NP1021 | 订单号格式错误 | 参数orderNo错误 订单号,必须为6位或10位长数字 |
NP1107 | 非法一网通支付协议号 | 参数agrNo错误 客户协议号。字符串,不超过30位。未签约客户,填写新增的协议号,用于协议开通;签约客户,填写客户协议号。非空。 |
NP1108 | 非法一网通支付协议开通流水号 | 参数merchantSerialNo错误 字符串,不超过20位。协议开通时非空。 |
NP1109 | 非法协议商户号 | 参数merchantNo错误 由银行在商户开户时确定。非空。 |
NP1110 | 非法协议用户ID | 参数userID错误 字符串,不超过20位。可为空 |
NP1111 | 非法协议手机号 | 参数Mobile错误 11位数字。可为空 |
NP1112 | 非法协议开通结果通知命令请求地址 | 参数signNoticeUrl错误 字符串,长度不超过100位。协议开通时非空。 |
NP1113 | 非法协议开通结果通知命令参数 | 参数signNoticePara错误 字符串,长度不超过128位。可为空 |
NP1124 | 商户URL返回地址格式错误 | 参数returnUrl错误 格式要求:“https://”或“http://”开头 |
以下是支付流程中的其他报错: | ||
NP2001 | 该商户只允许使用专业版进行支付 | 只允许进行专业版支付的商户,不允许接入一网通支付 |
NP2028 | 该商户不允许进行协议支付 | 商户不在一网通支付白名单中 |
NP4010 | 查询协议支付信息失败 | 查询客户协议信息失败(与中间业务通讯),后面会有具体错误原因: 后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。 错误信息中带错误码“NP8016”:与后端系统通讯失败。联系后台处理人察看系统运行情况 |
NP4011 | 查询一网通用户信息失败 | 查询一网通用户状态失败(与一网通BServer通讯),后面会有具体错误原因: 后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。 错误信息中带错误码“NP8005”:与后端系统通讯失败。联系后台处理人察看系统运行情况 |
NP4012 | 一网通用户状态异常 | 查询一网通用户状态成功,但用户状态异常。根据提示信息进行相应处理。 |
NP4013 | 查询绑定卡列表信息失败 | 查询绑定卡片列表失败(与一网通BServer通讯,BServer后台对接综合支付平台),后面会有错误原因: 后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。 错误信息中带错误码“NP8005”:与后端系统通讯失败。联系后台处理人察看系统运行情况 |
NP4014 | 抱歉,您解绑了所有卡片,目前绑定卡列表为空,请绑定后重试 | 客户绑定卡片列表中无“支付卡”。 |
NP0020 | 请求处理失败,请重新提交 | 支付密码解密失败(一般是商户公钥与系统配置的私钥不匹配) |
NP4004 | 支付请求处理失败 | 支付请求提交失败(与NPSServer通讯,BServer后台对接收单),后面会有错误原因: 后台返回的错误信息:此时根据提示进行处理或找后台系统接口人进行处理。 错误信息中带错误码“NP8005”:与后端系统通讯失败。联系后台处理人察看系统运行情况 |
NP8005 | BServer业务处理通讯失败 | 与BServer系统通讯失败。需根据场景进行分析:1、如填写完支付密码提交时报错,参看错误码NP4004中“NP8005”处理 |
NP1122 | 无效订单:签名验证失败 | Sign加密签名不匹配,检查参数排序是否一致,参数是否按规定来传,算法是否正确 |
NP1123 | 参数格式不正确 | 检查json格式是否正确 |
NP1125 | 商户编码错误 | 检查是否使用了规定的编码方式 |
NP1126 | 商户请求方式错误 | 检查是否使用了规定的请求方式,只支持Post方式 |
NP1128 | 扩展信息解密错误或扩展信息格式错误 | extendInfo加密算法有误或参数数据格式错误 |
NP1129 | 扩展信息加密类型错误 | extendInfoEncrypType未送RC4或DES |