二维码支付

二维码支付API

1. 接口描述

本接口用于招商银行APP小程序商户对用户发起扣款,目前支持两种调用方式:
1)cmbnetpayapi调用,通过该方式客户可体验一网通支付最新版支付流程,并解决小程序与支付导航栏兼容问题。推荐优先采用cmbnetpayapi调用方式,具体方法请参考章节2;
2)直接调用,具体调用地址、接口定义和调用方法参考本文档以下内容。

2. cmbnetpayapi调用

2.1 新开窗口加载支付页面

系统交互图.png

步骤1:用户在商户的订单页面点击立即支付;
步骤2:用户在支付页面进行核身等操作,核身完成后展示支付成功页;
步骤3:用户在支付成功页点击返回商户,支付系统会关闭当前的支付webview,返回商户的webview,再跳转到商户设置的返回页面。

2.2 发起支付

1)下载cmblapi最新版本并引入,请参考cmblapi调用方法
2)下载cmbnetpayapi最新版本并引入;

cmbnetpayapi_v1.1.0_min.zip

3)在HTML中引入cmblapi和cmbnetpayapi模块,建议直接在<head>中引入:

<head>
<script src="cmbnetpayapi.js"></script>
<script src="cmblapi.js"></script>
 </head>

4)调用cmbnetpay(param),其中param参数说明如下:

属性类型必填描述默认值
showTypeStringM新开窗口加载,通过客户端的gofunc接口请求。当showType为popup时以弹出窗口方式加载支付页面popup
jsonRequestDataStringM支付请求数据,采用json格式,参考3.2章节内容
popupParamobjectM参考以下payType和ReturnMethod定义
payTypestringMpayType为QRcode:二维码支付QRcode
ReturnMethodstringMMerchantView: 支付完成后由支付系统自动关闭支付窗口,回到商户的窗口加载商户的returnurlMerchantView


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://121.15.180.66:801/netpayment/BaseHttp.dll?MB_APPQRPay

3.2 请求报文

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

参数名称JSON键值类型(长度)必填描述示例
接口版本号versionString(3)M固定为“1.0”1.0
参数编码charsetString(8)M固定为“UTF-8”UTF-8
报文签名signStringM使用支付密钥对reqData内的数据进行签名
签名算法signTypeStringM固定为“SHA-256”SHA-256
请求数据reqData
请求时间dateTimeString(14)M格式:yyyyMMddHHmmss
含义:商户发起该请求的当前时间,精确到秒
20161216140241
分行号branchNoString(4)M商户分行号,4位数字0755
商户号merchantNoString(6)M商户号,6位数字000054
订单日期dateString(8)M格式:yyyyMMdd
含义:订单的日期
20161024
订单号orderNoString(32)M订单号。支持6-32位(含6和32)间任意位数的订单号,支持不固定位数,支持数字+字母(大小字母)随意组合。由商户生成,一天内不能重复。订单日期+订单号唯一定位一笔订单。9999153784
订单金额amountString(14)M格式:xxxx.xx
固定两位小数,最大11位整数
0.01
过期时间跨度expireTimeSpanString(2)M必须为大于零的整数,单位为分钟。
该参数指定当前支付请求必须在指定时间跨度内完成(从系统收到支付请求开始计时),否则按过期处理。一般适用于航空客票等对交易完成时间敏感的支付请求。
1
成功支付结果通知地址payNoticeUrlString(256)M商户接收成功支付结果通知的地址,不能带商户参数。http://www.merchant.com/path/payNotice.do
成功支付结果通知附加参数payNoticeParaString(256)O该参数在发送成功支付结果通知时,将原样返回商户
注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。
aaa
成功页返回商户地址returnUrlString(256)O支付成功页面上“返回商户”按钮跳转地址。为空则返回招商银行APP首页。http://www.merchant.com/path/return.do
商户用户IPclientIPString(64)O商户取得的客户IP,如果有多个IP用逗号”,”分隔。99.12.43.61
允许支付的卡类型cardTypeString(1)O默认对支付卡种不做限制
如果为A,则只允许储蓄卡支付,禁止信用卡支付;其他值储蓄卡和信用卡均可支付

二级商户编码subMerchantNoString(30)O当前订单为商户的二级商户的订单时需要传送;必须为数字或英文字母
二级商户名称subMerchantNameString(40)O当前订单为商户的二级商户的订单时需要传送;
加密类型encrypTypeStringCRC4:使用RC4算法对加密数据进行加密,加密密钥为支付密钥。 DES:使用DES算法对加密数据进行加密,加密密钥为商户支付密钥的前8位,不足8位则右补0。 注意:如果加密数据字段非空,该字段必填RC4
加密数据encrypDataStringOjson格式写入的加密数据,并使用encrypType指定的算法加密
使用信息
使用encrypType指定的加密算法加密后的扩展信息。明文格式字符串格式如:{"addressCity":"440300","addressMobile":"18106989120","productType":"000518"}
注意:加密后的密文必须转换为16进制字符串
FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9
开通实名认证时,需上送以下信息(商户默认不上送):
客户实名认证方式userAuthTypeString(2)O主动支付客户实名认证方式:
A:按照免密支付协议号对应的客户信息认证
A
认证信息

userAuthInfo

String(32)OA模式下上送免密支付协议号

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键值类型(长度)必填描述示例
订单收货城市addressCityString(6)O商户接口上送。使用行政区划代码,六位440300
订单收货手机号addressMobileString(11)O商户接口上送。尽量提供完整号码,如商户不愿意提供,可仅提供后四位18106989120
商品及服务标识productTypeString(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无效的商户返回URLUrl格式不正确
NP1126Http请求方式不正确只支持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”:与后端系统通讯失败。联系后台处理人察看系统运行情况
NP8005BServer业务处理通讯失败与BServer系统通讯失败。需根据场景进行分析:1、如填写完支付密码提交时报错,参看错误码NP4004中“NP8005”处理
NP1122无效订单:签名验证失败Sign加密签名不匹配,检查参数排序是否一致,参数是否按规定来传,算法是否正确
NP1123参数格式不正确检查json格式是否正确
NP1125商户编码错误检查是否使用了规定的编码方式
NP1126商户请求方式错误检查是否使用了规定的请求方式,只支持Post方式