主动冻结

资金冻结

1. 接口描述

功能简述:

本接口用于招商银行APP小程序商户发起需客户主动授权的资金冻结交易。

约束条件:

1、 商户管理系统已配置支持“资金冻结”
2、 客户资金最长支持冻结三年

正常流程:

1、 报文合性校验
2、 资金冻结处理
3、 异步发送交易处理结果回调通知

异常流程:

1、 商户在招行侧开通IP白名单控制,请求源IP不在IP白单中
2、 报文验签失败
3、 报文参数非法
4、 商户未在招行侧申请开通“资金冻结”功能

2. 请求方式

2.1 发起支付

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参数说明如下:

属性类型必填描述默认值

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":"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 请求报文

参数类型(长度)必填描述示例
charsetString(8)M参数编码,固定为“UTF-8”(默认)UTF-8
jsonRequestDataStringMJson格式的请求参数,详见jsonRequestData定义

jsonRequestData参数定义

参数名称JSON键值类型(长度)必填描述示例
接口版本号versionString(3)M固定为“1.0”1.0
报文签名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
含义:订单的日期
20161216
订单号orderNoString(32)M6-32位数字或字母,由商户生成,一天内不能重复。
订单日期+订单号唯一定位一笔订单。
9999153784
冻结金额amountString(14)M格式:xxxx.xx
固定两位小数,最大11位整数
0.01
到期自动解冻日期unfreezeDateString(8)M格式:yyyyMMdd
含义:到期后招行自动解冻客户资金
0.01
过期时间跨度expireTimeSpanString(2)M必须为大于零的整数,单位为分钟。
该参数指定当前支付请求必须在指定时间跨度内完成(从系统收到支付请求开始计时),否则按过期处理。一般适用于航空客票等对交易完成时间敏感的支付请求。
1
成功冻结结果通知地址payNoticeUrlString(256)M商户接收成功支付结果通知的地址,不能带商户参数。http://www.merchant.com/path/payNotice.do
成功支付结果通知附加参数payNoticeParaString(256)O该参数在发送成功支付结果通知时,将原样返回商户
注意:该参数可为空,商户如果需要不止一个参数,可以自行把参数组合、拼装,但组合后的结果不能带有’&’字符。
aaa
成功页返回商户地址returnUrlString(256)O支付成功页面上“返回商户”按钮跳转地址。为空则不显示返回商户按钮。http://www.merchant.com/path/return.do
商户用户IPclientIPString(64)O商户取得的客户IP,如果有多个IP用逗号”,”分隔。99.12.43.61
二级商户编码subMerchantNoString(30)O当前订单为商户的二级商户的订单时需要传送;必须为数字或英文字母
二级商户名称subMerchantNameString(100)O当前订单为商户的二级商户的订单时需要传送;
二级商户类别编码subMerchantTPCodeString(7)O当前订单为商户的二级商户的订单时需要传送;必须为数字或英文字母
二级商户类别名称subMerchantTPNameString(100)O当前订单为商户的二级商户的订单时需要传送;必须为数字或英文字母
加密类型encrypTypeStringORC4:使用RC4算法对加密数据进行加密,加密密钥为支付密钥。 DES:使用DES算法对加密数据进行加密,加密密钥为商户支付密钥的前8位,不足8位则右补0。 注意:如果使用addressCity、addressMobile、productType参数,该字段必填RC4
加密数据encrypDataStringOjson格式写入的加密数据,并使用encrypType指定的算法加密
使用信息
使用encrypType指定的加密算法加密后的扩展信息。明文格式字符串格式如:{"addressCity":"440300","addressMobile":"18106989120","productType":"000518"}
注意:1.加密后的密文必须转换为16进制字符串
2.如果使用addressCity、addressMobile、productType参数,该字段必填
FC779C8E6953AC0C97BE115D61FE1669AECBE5836DF120A84157D9515DFD375E00B0538C85B930E6A33BB9E0213150E07953DEB1D4E30EF4356FF0B2700357881B3A8670B37C25C76DF2378DF9
商品描述productDescString(40)O1、在支付成功后,附加在短信通知中
2、最大40个字节,1个中文占用2个字节
3、支持中文、字母(大小写)、数字、空格、标点符号,任意组合
4、不支持英文格式的单双引号、加号(+)、反斜杠(\)、&、」

开通实名认证时,需上送以下信息(商户默认不上送):
客户实名认证方式userAuthTypeString(2)O主动支付客户实名认证方式:
A:按照免密支付协议号对应的客户信息认证
A
认证信息userAuthInfoString(32)OA模式下上送免密支付协议号111222333
  • 扩展信息

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

    a. 扩展信息字段可传的参数

参数名称JSON键值类型(长度)必填描述示例
订单收货城市addressCityString(6)O商品接口上送,使用行政区划代码,六位440300
订单收货手机号addressMobileString(11)O商品接口上送,尽量提供完整号码,如商户不愿意提供,可仅提供后四位18106989120
商品及服务标识productTypeString(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位数字,请咨询开户的招商银行分支机构;