二维码支付API

请求地址

生产环境
https://netpay.cmbchina.com/netpayment/BaseHttp.dll?MB_APPQRPay

测试环境
http://121.15.180.66:801/netpayment/BaseHttp.dll?MB_APPQRPay

请求报文

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

参数名称 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
含义:商户发起该请求的当前时间,精确到秒
20161216140241
分行号 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)间任意位数的订单号,支持不固定位数,支持数字+字母(大小字母)随意组合。由商户生成,一天内不能重复。订单日期+订单号唯一定位一笔订单。 9999153784
金额 amount String(14) M 格式:xxxx.xx
固定两位小数,最大11位整数
0.01
过期时间跨度 expireTimeSpan String(2) O 必须为大于零的整数,单位为分钟。
该参数指定当前支付请求必须在指定时间跨度内完成(从系统收到支付请求开始计时),否则按过期处理。一般适用于航空客票等对交易完成时间敏感的支付请求。
30
成功支付结果通知地址 payNoticeUrl String(256) M 商户接收成功支付结果通知的地址,不能带商户参数。 http://www.merchant.com/path/payNotice.do
成功支付结果通知附加参数 payNoticePara String(256) O 该参数在发送成功支付结果通知时,将原样返回商户
注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。
aaa
成功页返回商户地址 returnUrl String(256) O 支付成功页面上“返回商户”按钮跳转地址。为空则不显示返回商户按钮。 http://www.merchant.com/path/return.do
商户用户IP clientIP String(64) O 商户取得的客户IP,如果有多个IP用逗号”,”分隔。 99.12.43.61
允许支付的卡类型 cardType String(1) O 默认对支付卡种不做限制
如果为A,则只允许储蓄卡支付,禁止信用卡支付;其他值储蓄卡和信用卡均可支付
二级商户编码 subMerchantNo String(30) O 当前订单为商户的二级商户的订单时需要传送;必须为数字或英文字母
二级商户名称 subMerchantName String(100) O 当前订单为商户的二级商户的订单时需要传送;
二级商户类型编码 subMerchantTPCode String(7) O 当前订单为商户的二级商户的订单时需要传送;必须为数字或字母
二级商户类型名称 subMerchantTPName String(100) O 当前订单为商户的二级商户的订单时需要传送;
加密类型 encrypType String C RC4:使用RC4算法对加密数据进行加密,加密密钥为支付密钥。 DES:使用DES算法对加密数据进行加密,加密密钥为商户支付密钥的前8位,不足8位则右补0。 注意:如果加密数据字段非空,该字段必填 RC4
加密数据 encrypData String O json格式写入的加密数据,并使用encrypType指定的算法加密
使用信息
使用encrypType指定的加密算法加密后的扩展信息。明文格式字符串格式如:{"addressCity":"440300","addressMobile":"18106989120","productType":"000518"}
注意:加密后的密文必须转换为16进制字符串
FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9

请求示例

1.json报文组织:

{
    "version":"1.0",
    "sign":"见签名处理章节",
    "signType":"SHA-256",
    "reqData":{
    "dateTime":"20161216140241",
    "date":"20161216",
    "orderNo":"9999153784",
    "amount":"0.01",
    "expireTimeSpan":"30",
    "payNoticeUrl":"http://www.merchant.com/path/payNotice.do",
    "payNoticePara":"aaa",
    "branchNo":"0755",
    "merchantNo":"000054",
    "returnUrl":"http://www.merchant.com/path/return.do",
    "clientIP":"99.12.43.61",
    "cardType":"",
    "encrypData":"FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9",
    "encrypType":"RC4",
    "subMerchantNo":"",
    "subMerchantName":"",
    "subMerchantTPCode":"",
    "subMerchantTPName":""
    }
 }

2.表单组织:

<form action="请求地址" method="post" >
    <input type="hidden" name="jsonRequestData" value='以上json字符串' /> 
    <input type="hidden" name="charset" value=’utf-8’ /> 
</form>

3.待签名字符串(未包含支付密钥):

amount=0.01&branchNo=0755&cardType=&clientIP=99.12.43.61&date=20161216&dateTime=20161216140241&encrypData=FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9&encrypType=RC4&expireTimeSpan=30&merchantNo=000054&orderNo=9999153784&payNoticePara=aaa&payNoticeUrl=http://www.merchant.com/path/payNotice.do&returnUrl=http://www.merchant.com/path/return.do&subMerchantName=&subMerchantNo=&subMerchantTPCode=&subMerchantTPName= 

4.扩展信息

扩展信息(encrypData)用于商户上送一些订单信息、用户信息。 json格式写入扩展信息,并使用encrypType指定的算法加密

参数名称 JSON键值 类型(长度) 必填 描述 示例
订单收货城市 addressCity String(6) O 商户接口上送。使用行政区划代码,六位 440300
订单收货手机号 addressMobile String(11) O 商户接口上送。尽量提供完整号码,如商户不愿意提供,可仅提供后四位 18106989120
商品及服务标识 productType String(12) O 商户接口上送。最大长度 000518

1)扩展信息字段的使用说明

json格式写入扩展信息,并使用encrypType指定的算法加密。加密算法如下:

首先将需传入的风控参数拼接成json,再使用RC4或DES加密生成16进制的字符串即为encrypData字段。encrypType取值为RC4时,密钥为商户支付密钥;取值为DES时,密钥为商户支付密钥的前8位,不足8位则右补0。RC4与DES算法参考附录中的RC4代码示例和DES代码示例。

响应报文

网页直接展示结果,无响应报文。
支付成功后有异步结果通知,失败无通知。

错误码

错误码 描述 解决方案
请求参数错误:
NP1016 分行号格式错误 参数branchID错误
商户开户分行号,4位数字,请咨询开户的招商银行分支机构;
NP1017 商户号格式错误 参数merchantNo错误
商户号,6位数字,由银行在商户开户时确定;//收单商户号
NP1020 金额格式错误 参数amount错误
订单总金额,格式为:xxxx.xx元;
NP1021 订单号格式错误 参数orderNo错误
订单号,必须为6位或10位长数字
NP1022 日期格式错误 参数date错误
Date:yyyyMMdd
NP1034 商户通知URL地址格式错误 参数paynoticeUrl错误或者returnUrl
格式要求:“https://”或“http://”开头
NP1035 商户通知参数超长 参数paynoticPara或错误
参数长度超过128个字节
NP1070 商户附加信息中,包含不允许的内容 参数paynoticPara错误
参数值不允许有脚本
NP1071 订单过期时间(分钟)格式错误 参数expireTimeSpan错误
必须为大于零的整数,单位为分钟。
NP1097 二级商户号格式不正确 二级商户号格式是否是全数字或者字母组合
NP1098 二级商户号长度超长 二级商户号最大长度为30
NP1099 二级商户类型编码格式不正确 二级商户类型编码为全数字
NP1100 二级商户类型编码长度超长 二级商户类型编码最大长度
NP1105 非法二级商户名称 二级商户名称最大长度为100
NP1106 非法二级商户类别名称 二级商户别名称最大长度为100
NP1122 商户签名不匹配 订单内容被篡改过,无效订单不予处理
NP1123 无效的Json参数 商户输入JSON参数不正确
NP1124 无效的商户返回URL Url格式不正确
NP1126 Http请求方式不正确 只支持Post请求方式
NP1128 非法的一网通支付风控数据 当前版本加密数据解密后为订单收货城市,订单手机号,商户及服务标识和用户代理的json格式
NP1129 无效的加密类型 加密类型只支持RC4或者DES
NP1133 无效的版本号 版本号固定为1.0
NP1134 无效的签名算法 仅支持SHA-256
NP2004 客户端IP不匹配或IP格式错误 确认IP格式,确认您本次将要支付的商品或服务,再重新生成订单进行支付
以下是支付流程中的其他报错:
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方式

关于网站迁移公告


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

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


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

2019年8月12日