二维码支付API
1. 接口描述
本接口用于招商银行APP小程序商户对用户发起扣款,目前支持两种调用方式:
1)cmbnetpayapi调用,通过该方式客户可体验一网通支付最新版支付流程,并解决小程序与支付导航栏兼容问题。推荐优先采用cmbnetpayapi调用方式,具体方法请参考章节2;
2)直接调用,具体调用地址、接口定义和调用方法参考本文档以下内容。
2. cmbnetpayapi调用
2.1 新开窗口加载支付页面
步骤1:用户在商户的订单页面点击立即支付;
步骤2:用户在支付页面进行核身等操作,核身完成后展示支付成功页;
步骤3:用户在支付成功页点击返回商户,支付系统会关闭当前的支付webview,返回商户的webview,再跳转到商户设置的返回页面。
2.2 发起支付
1)下载cmblapi最新版本并引入,请参考cmblapi调用方法;
2)下载cmbnetpayapi最新版本并引入;
3)在HTML中引入cmblapi和cmbnetpayapi模块,建议直接在<head>中引入:
<head> <script src="cmbnetpayapi.js"></script> <script src="cmblapi.js"></script> </head>
4)调用cmbnetpay(param),其中param参数说明如下:
属性 | 类型 | 必填 | 描述 | 默认值 |
showType | String | M | 新开窗口加载,通过客户端的gofunc接口请求。当showType为popup时以弹出窗口方式加载支付页面 | popup |
jsonRequestData | String | M | 支付请求数据,采用json格式,参考3.2章节内容 | |
popupParam | object | M | 参考以下payType和ReturnMethod定义 | |
payType | string | M | payType为QRcode:二维码支付 | QRcode |
ReturnMethod | string | M | MerchantView: 支付完成后由支付系统自动关闭支付窗口,回到商户的窗口加载商户的returnurl | MerchantView |
5)示例报文:新开窗口加载—商户页面展示returnUrl
var RequestData = '{"version":"1.0","sign":"xxxx","signType":"SHA-256","reqData":{"dateTime":"20200727215354","date":"20200727","orderNo":"a0000000000000009999242417","amount":"0.01","expireTimeSpan":"30","payNoticeUrl":"http://127.0.0.1/test.html","payNoticePara":"aaa","branchNo":"0755","merchantNo":"008586","returnUrl":"http://127.0.0.1/MerchantBack.html","clientIP":"192.168.0.1","cardType":"","encrypData":"xxxx","encrypType":"RC4","subMerchantNo":"","subMerchantName":"","subMerchantTPCode":"","subMerchantTPName":""}}' var param = { showType:'popup', jsonRequestData: RequestData, popupParam:{ payType:"default", ReturnMethod:"MerchantView" } } cmbnetpay(JSON.stringify(param));
3. 直接调用
3.1 请求地址
生产环境
https://netpay.cmbchina.com/netpayment/BaseHttp.dll?MB_APPQRPay
测试环境
http://netpay.netpay.bas.cmburl.cn:801/netpayment/BaseHttp.dll?MB_APPQRPay
3.2 请求报文
报文的参数名: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) | M | 必须为大于零的整数,单位为分钟。 该参数指定当前支付请求必须在指定时间跨度内完成(从系统收到支付请求开始计时),否则按过期处理。一般适用于航空客票等对交易完成时间敏感的支付请求。 | 1 |
成功支付结果通知地址 | payNoticeUrl | String(256) | M | 商户接收成功支付结果通知的地址,不能带商户参数。 | http://www.merchant.com/path/payNotice.do |
成功支付结果通知附加参数 | payNoticePara | String(256) | O | 该参数在发送成功支付结果通知时,将原样返回商户 注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。 | aaa |
成功页返回商户地址 | returnUrl | String(256) | O | 支付成功页面上“返回商户”按钮跳转地址。为空则返回招商银行APP首页。 | 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(40) | 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 |
开通实名认证时,需上送以下信息(商户默认不上送): | |||||
客户实名认证方式 | userAuthType | String(2) | O | 主动支付客户实名认证方式: A:按照免密支付协议号对应的客户信息认证 B:用户信息expendUserID C:用户信息uniqueUserID | A |
认证信息 | userAuthInfo | String(32) | O | A模式下上送免密支付协议号 B和C模式用于判断下单用户和支付用户是否一致(B和C模式可能带有+,需做urlencode处理) | 111222333 |
3.3 请求示例
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":"127.0.0.1", "cardType":"", "encrypData":"FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9", "encrypType":"RC4", "subMerchantNo":"", "subMerchantName":"", "subMerchantTPCode":"", "subMerchantTPName":"" "userAuthType":"A", "userAuthInfo":"111222333" } }
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=127.0.0.1&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代码示例。
3.4 响应报文
网页直接展示结果,无响应报文。
支付成功后有异步结果通知,失败无通知。
3.5 错误码
错误码 | 描述 | 解决方案 |
请求参数错误: | ||
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方式 |