一网通支付
1. 接口描述
本接口用于招商银行APP小程序商户对用户发起扣款,目前支持以下两种调用方式:
1)cmbnetpayapi调用,通过该方式客户可体验一网通支付最新版支付流程,并解决小程序与支付导航栏兼容问题。新商户默认请采用cmbnetpayapi调用方式,具体方法请参考章节2;
2)JS-SDK调用(招商APP8.2及以上版本支持),具体调用方式请参考招商银行APP小程序开放平台;
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为空或default:一网通APP内支付 | default |
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 请求报文
参数 | 类型(长度) | 必填 | 描述 | 示例 |
charset | String(8) | M | 参数编码,固定为“UTF-8”(默认) | UTF-8 |
jsonRequestData | String | M | Json格式的请求参数,详见jsonRequestData定义 |
jsonRequestData参数定义
参数名称 | JSON键值 | 类型(长度) | 必填 | 描述 | 示例 | |
接口版本号 | version | String(3) | M | 固定为“1.0” | 1.0 | |
报文签名 | 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 含义:订单的日期 | 20161216 | |
订单号 | orderNo | String(32) | M | 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 | 当前订单为商户的二级商户的订单时需要传送; | ||
允许的支付方式 | payModeType | String(2) | O | 默认不设限制,允许微信支付。 空或00:不设限制; 01:仅不允许微信支付 | ||
加密类型 | encrypType | String | O | RC4:使用RC4算法对加密数据进行加密,加密密钥为支付密钥。 DES:使用DES算法对加密数据进行加密,加密密钥为商户支付密钥的前8位,不足8位则右补0。 注意:如果使用addressCity、addressMobile、productType参数,该字段必填 | RC4 | |
加密数据 | encrypData | String | O | json格式写入的加密数据,并使用encrypType指定的算法加密 使用信息 使用encrypType指定的加密算法加密后的扩展信息。明文格式字符串格式如:{"addressCity":"440300","addressMobile":"18106989120","productType":"000518"} 注意:1.加密后的密文必须转换为16进制字符串 2.如果使用addressCity、addressMobile、productType参数,该字段必填 | FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9 | |
订单收货城市 | addressCity | String(6) | O | 商户接口上送。使用行政区划代码,六位 | 440300 | |
订单收货手机号 | addressMobile | String(11) | O | 商户接口上送。尽量提供完整号码,如商户不愿意提供,可仅提供后四位 | 18106989120 | |
商品及服务标识 | productType | String(12) | O | 商户接口上送。最大长度 | 000518 | |
开通实名认证时,需上送以下信息(商户默认不上送): | ||||||
客户实名认证方式 | userAuthType | String(2) | O | 主动支付客户实名认证方式: A:按照免密支付协议号对应的客户信息认证 B:用户信息expendUserID C:用户信息uniqueUserID | A | |
认证信息 | userAuthInfo | String(32) | O | A模式下上送免密支付协议号 B和C模式用于判断下单用户和支付用户是否一致(B和C模式可能带有+,需做urlencode处理) | 111222333 |
3.2 示例报文
1) jsonRequestData报文组织:
{ "version":"1.0", "charset":"UTF-8", "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)待签名字符串(未包含支付密钥):
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=
3.3 响应报文
网页直接展示结果,无响应报文。
支付成功后有异步结果通知,失败无通知。
3.4 错误码
错误码 | 描述 | 解决方案 |
请求参数错误: | ||
NP1016 | 分行号格式错误 | 参数branchNo错误 商户开户分行号,4位数字,请咨询开户的招商银行分支机构; |
NP1017 | 商户号格式错误 | 参数merchantNo错误 商户号,6位数字,由银行在商户开户时确定;//收单商户号 |
NP1020 | 金额格式错误 | 参数amount错误 订单总金额,格式为:xxxx.xx元; |
NP1021 | 订单号格式错误 | 参数orderNo错误 订单号,必须为6位或10位长数字 |
NP1022 | 日期格式错误 | 参数dateTime或date错误 Date: yyyyMMdd,TS:yyyyMMddHHmmss |
NP1034 | 商户通知URL地址格式错误 | 参数payNoticeUrl错误 格式要求:“https://”或“http://”开头 |
NP1035 | 商户通知参数超长 | 参数payNoticePara或signNoticePara错误 参数长度超过128个字节 |
NP1070 | 商户附加信息中,包含不允许的内容 | 参数payNoticePara或signNoticePara错误 参数值不允许有脚本 |
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方式 |