资金冻结
1. 接口描述
功能简述:
本接口用于招商银行APP小程序商户发起需客户主动授权的资金冻结交易。
约束条件:
1、 商户管理系统已配置支持“资金冻结”
2、 客户资金最长支持冻结三年
正常流程:
1、 报文合性校验
2、 资金冻结处理
3、 异步发送交易处理结果回调通知
异常流程:
1、 商户在招行侧开通IP白名单控制,请求源IP不在IP白单中
2、 报文验签失败
3、 报文参数非法
4、 商户未在招行侧申请开通“资金冻结”功能
2. 请求方式
2.1 发起支付
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 | FreezePay | FreezePay |
ReturnMethod | string | M | MerchantView: 支付完成后由支付系统自动关闭支付窗口,回到商户的窗口加载商户的returnurl | MerchantView |
5)示例报文:新开窗口加载—商户页面展示returnUrl
var RequestData = ' {"version":"1.0","sign":"xxxxxx","signType":"SHA-256","reqData":{"dateTime":"20201129152208","branchNo":"0755","merchantNo":"000054","date":"20201129","orderNo":"f0000000000000009999537910","amount":"0.01","unfreezeDate":"20201130","expireTimeSpan":"30","payNoticeUrl":"http://192.168.0.1:801/xxxx.html","payNoticePara":"aaa","returnUrl":"http://192.168.0.1:801/aaa.html","clientIP":"192.168.0.1","subMerchantNo":"","subMerchantName":"","subMerchantTPCode":"","subMerchantTPName":"","encrypData":"aaa","encrypType":"RC4","userAuthType":"A","userAuthInfo":"112233","productDesc":"aaa"}} ' var param = { showType:'popup', jsonRequestData: RequestData, popupParam:{ payType:"default", ReturnMethod:"MerchantView" } } cmbnetpay(JSON.stringify(param));
2.2 请求报文
参数 | 类型(长度) | 必填 | 描述 | 示例 |
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 | |
到期自动解冻日期 | unfreezeDate | String(8) | M | 格式:yyyyMMdd 含义:到期后招行自动解冻客户资金 要求:最长不超过3年 | 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 | 支付成功页面上“返回商户”按钮跳转地址。为空则不显示返回商户按钮。 | http://www.merchant.com/path/return.do | |
商户用户IP | clientIP | String(64) | O | 商户取得的客户IP,如果有多个IP用逗号”,”分隔。 | 99.12.43.61 | |
二级商户编码 | subMerchantNo | String(30) | O | 当前订单为商户的二级商户的订单时需要传送;必须为数字或英文字母 | ||
二级商户名称 | subMerchantName | String(100) | O | 当前订单为商户的二级商户的订单时需要传送; | ||
二级商户类别编码 | subMerchantTPCode | String(7) | O | 当前订单为商户的二级商户的订单时需要传送;必须为数字或英文字母 | ||
二级商户类别名称 | subMerchantTPName | String(100) | O | 当前订单为商户的二级商户的订单时需要传送;必须为数字或英文字母 | ||
加密类型 | 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 | |
商品描述 | productDesc | String(40) | O | 1、在支付成功后,附加在短信通知中 2、最大40个字节,1个中文占用2个字节 3、支持中文、字母(大小写)、数字、空格、标点符号,任意组合 4、不支持英文格式的单双引号、加号(+)、反斜杠(\)、&、」 | ||
开通实名认证时,需上送以下信息(商户默认不上送): | ||||||
客户实名认证方式 | userAuthType | String(2) | O | 主动支付客户实名认证方式: A:按照免密支付协议号对应的客户信息认证 | A | |
认证信息 | userAuthInfo | String(32) | O | A模式下上送免密支付协议号 | 111222333 |
扩展信息
扩展信息(encrypData)用于商户上送一些订单信息、用户信息。 json格式写入扩展信息,并使用encrypType指定的算法加密。
a. 扩展信息字段可传的参数
参数名称 | JSON键值 | 类型(长度) | 必填 | 描述 | 示例 |
订单收货城市 | addressCity | String(6) | O | 商品接口上送,使用行政区划代码,六位 | 440300 |
订单收货手机号 | addressMobile | String(11) | O | 商品接口上送,尽量提供完整号码,如商户不愿意提供,可仅提供后四位 | 18106989120 |
商品及服务标识 | productType | String(12) | O | 商品接口上送 | 000518 |
b. 扩展信息字段的使用说明
json格式写入扩展信息,并使用encrypType指定的算法加密。加密算法如下:
收单将需传入的风控参数拼接成json,再使用RC4或DES加密生成16进制的字符串即为encrypData字段。encrypType取值为RC4时,密钥为商户支付密钥;取值为DES时,密钥为商户支付密钥的前8位,不足8位则右补0。RC4与DES算法参考附录中的RC4代码示例和DES代码示例。
2.3 示例报文
1) jsonRequestData报文组织:
{ "version":"1.0", "charset":"UTF-8", "sign":"见签名处理章节", "signType":"SHA-256", "reqData":{ "dateTime":"20201129152208", "branchNo":"0755", "merchantNo":"000054", "date":"20201129", "orderNo":"f0000000000000009999537910", "amount":"0.01", "unfreezeDate":"20201130", "expireTimeSpan":"30", "payNoticeUrl":"http://192.168.0.1:801/xxxx.html", "payNoticePara":"aaa", "returnUrl":"http://192.168.0.1:801/aaa.html", "clientIP":"192.168.0.1", "subMerchantNo":"", "subMerchantName":"", "subMerchantTPCode":"", "subMerchantTPName":"", "encrypData":"aaa", "encrypType":"RC4", "userAuthType":"A", "userAuthInfo":"112233", "productDesc":"aaa" } }
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=0731&clientIP=192.168.0.1&date=20201209&dateTime=20201209155851&encrypData=aaa&encrypType=RC4&expireTimeSpan=30&merchantNo=000034&orderNo=f0000000000000009999537910&payNoticePara=aaa&payNoticeUrl=http://192.168.0.1:801/XXXXXX.html&productDesc=aaa&returnUrl=http://192.168.0.1:801/aaa.html&subMerchantName=&subMerchantNo=&subMerchantTPCode=&subMerchantTPName=&unfreezeDate=20201210&userAuthInfo=111222&userAuthType=A
3.4 响应报文
网页直接展示结果,无响应报文。
支付成功后有异步结果通知,失败无通知。
3.5 错误码
错误码 | 描述 | 解决方案 |
请求参数错误: | ||
NP1016 | 分行号格式错误 | 参数branchNo错误 商户开户分行号,4位数字,请咨询开户的招商银行分支机构; |