主动冻结

交易状态查询

1. 接口介绍

功能简述:

本接口用于商户主动查询“资金冻结交易、资金解冻交易、资金冻结完成扣款交易"的处理状态。

应用场景:

1、 当商户后台、网络、服务器等出现异常,或因为其他可能发生的未知原因,商户后台最终未接收到支付异步通知
2、 商户调用交易接口后,返回系统错误等情况

约束条件:

商户调用了冻结、解冻或冻结完成接口后,如果没收到同步应答或异步通知,可以通过本接口主动查询交易的处理状态。请注意:不要在调用冻结、解冻或冻结完成接口的同时,并发调用查询接口确认终态。

正常流程:

1、 报文合性校验
2、 报文参数校验
3、 同步返回交易处理状态

异常流程:

1、 商户在招行侧开通IP白名单控制,请求源IP不在IP白单中
2、 报文验签失败
3、 报文参数非法
4、 要查询的交易不存在

2. 请求地址

测试环境URL:

http://121.15.180.66:801/netpayment_directlink_nosession/QueryFreeze.do

生产环境URL:

https://merchserv.netpay.cmbchina.com/merchserv/QueryFreeze.do

3. 请求报文

请求报文参数类型(长度)必填描述示例
jsonRequestDataStringMjson格式的请求参数,详见jsonRequestData定义

jsonRequestData参数定义

参数名类型(长度)必填描述示例
versionString(3)M固定为2.02.0
charsetString(8)M编码格式,固定为UTF-8UTF-8
signStringM使用商户支付密钥对reqData内的数据进行签名
signTypeStringM固定为SHA-256SHA-256
reqData请求数据


dateTimeString(14)M请求时间,商户发起该请求的时间,精确到秒。
格式:yyyyMMddHHmmss
20160623101430
branchNoString(4)M商户分行号,4位数字0755
merchantNoString(6)M商户号,6位数字002346
typeString(3)M查询类型

FRZ:冻结

FRU:解冻

FRC:冻结完成

FRZ
dateString(8)M商户冻结、解冻、冻结完成扣款交易日期YYYYMMDD20160623
merchantSerialNoString(32)M商户冻结、解冻、冻结完成扣款交易流水号2016062310143088
当type=FRU或FRC时,需另外上送以下参数:
origDateString(8)C原商户资金冻结交易日期YYYYMMDD20160623
origOrderNoString(32)C原商户资金冻结订单号2016062310143011

请求示例:

json报文组织:

{
    "version":"2.0",
    "charset":"UTF-8",
    "sign":"见签名处理章节",
    "signType":"SHA-256",
    "reqData":
    {
        "dateTime":"20201126195054",
        "branchNo":"0731",
        "merchantNo":"000032",
        "type":"FRZ",
        "date":"20201126",
        "merchantSerialNo":"20201119181621677001",
        "origDate":"",
        "origOrderNo":"
        }
}

表单组织:

<form action="请求地址" method="post" >
      <input type="hidden" name="jsonRequestData" value='以上json字符串' /> 
      <input type="hidden" name="charset"  value='UTF-8' />
</form>

待签名字符串(未包含支付密钥):

branchNo=0731&date=20201126&dateTime=20201126195054&merchantNo=000032&merchantSerialNo=20201119181621677001&origDate=&origOrderNo=&type=FRZ

4. 响应报文

参数名类型(长度)必填描述示例
versionString(3)M固定为2.02.0
charsetString(8)M参数编码,固定为UTF-8UTF-8
signStringM报文签名,使用商户支付密钥
对rspData内的数据进行验签

signTypeStringM签名算法,固定为SHA-256SHA-256
rspData应答数据


rspCodeStringM处理结果返回码

SUC0000:请求处理成功

其他:请求处理失败
SUC0000
rspMsgStringC请求处理失败时返回错误原因描述
dateTimeString(14)M银行响应该请求的时间,格式yyyyMMddHHmmss20160623101430
branchNoString(4)M商户分行号,4位数字0755
merchantNoString(6)M商户号,6位数字002346
dateString(8)M格式yyyyMMdd20160623
merchantSerialNoString(32)M商户交易流水号2016062310143088
bankSerialNoString(20)M银行订单流水号2016062310143099
origDateString(8)C原商户资金冻结交易日期YYYYMMDD20160623
origOrderNoString(32)C原商户资金冻结订单号2016062310143011
currencyString(2)M交易币种10:人民币
amountStringM交易金额,以元为单位,如10.01表示10元零1分10.01
settleAmountStringC结算金额(冻结完成交易查询时返回),以元为单位10.01
feeStringC手续费金额(冻结完成交易查询时返回),以元为单位0.01
discountAmountStringC优惠金额(冻结完成交易查询时返回),以元为单位10.01
cardTypeString(2)O交易卡类型

02:本行借记卡

03:本行信用卡

08:他行借记卡

09:他行信用卡

02
bankDateString(8)M银行处理日期,格式yyyyMMdd20160623
bankTimeString(6)M银行处理时间,格式HHmmss101430
orderstatusStringM查询交易处理状态

S:成功

F:失败

X:未知

S
unfreezeDateString(8)O到期自动解冻日期(冻结交易查询时返回)20210101
totalUnfreezeAmountStringM

原冻结交易累计已解冻金额:

1、自然日期小于unfreezeDate,该金额返回“原冻结交易商户累计发起已解冻的金额”,以元为单位,格式XXXX.XX

2、超过unfreezeDate后,该金额返回“原冻结交易的冻结金额减掉累计冻结完成扣款金额”

10.01
totalPayAmountStringM原冻结交易由商户发起累计冻结完成扣款金额,以元为单位,格式XXXX.XX10.01
restFreezeAmountStringM

原冻结交易剩余冻结金额:

1、自然日期小于unfreezeDate,该金额返回原冻结交易剩余冻结金额,以元为单位,格式XXXX.XX

2、超过unfreezeDate后,该金额返回0,代表商户不能再发起解冻或冻结完成扣款交易

10.01
以下字段联系招行配置控制参数后返回(默认不返回):
uniqueUserIDString(30)C支付用户ID,由身份证+姓名生成(推荐使用)UQwanCunLbp6cl1RbDFODrhLrAa48=
expandUserIDString(30)C一网通用户ID,由一网通ID生成(招行一网通用户的身份标识)EUfirwdVQVKhffJmjQhMod0dS6GYY=

相应示例:

正常json报文组织:

{
    "sign":"见签名处理章节",
    "signType":"SHA-256",
    "version":"2.0",
    "charset":"UTF-8",
    "rspData":{
        "rspCode":"SUC0000",
        "rspMsg":"",
        "dateTime":"20201126200454",
        "branchNo":"0731",
        "merchantNo":"000032",
        "date":"20201126",
        "merchantSerialNo":"20201119181621677001",
        "bankSerialNo":"115W309A061ABD00000A",
        "origDate":"",
        "origOrderNo":"",
        "bankDate":"20201126",
        "bankTime":"144606",
        "currency":"10",
        "amount":"1",
        "fee":"0",
        "settleAmount":"0",
        "discountAmount":"0",
        "cardType":"02",
        "orderStatus":"S",
        "unfreezeDate":"20201122",
        "totalUnfreezeAmount":"0",
        "totalPayAmount":"0",
        "restFreezeAmount":"1"
        }
}

异常json报文组织:

{
    "sign":"E4561A2940414F1EDE3DC7CE145600B0A32D33D21E3852CBF2D0C1A655611609",
    "signType":"SHA-256",
    "version":"2.0",
    "charset":"UTF-8",
    "rspData":
    {
        "rspCode":"MSS1022",
        "rspMsg":"NP1022.日期格式错误"
    }
}

5. 错误码

错误码描述解决方案
MSS9900请求数据Json转换异常检验并修改请求报文数据
MSS9002版本号错误Version固定为“2.0”
MSS9003签名算法错误目前仅支持“SHA-256”
MSS3411签名错误验证签名是否正确,请参考签名示例
MSS1016分行号格式错误分行号格式应为4位数字
MSS1017商户号格式错误商户号格式应为6位数字
MSS3110无效查询类型查询类型只能为“FRZ、FRC、FRU”
MSS1022订单日期或者时间格式错误日期应为yyyyMMdd格式,
时间应为yyyyMMddHHmmss格式
MSS1115原商户冻结交易日期格式不正确日期应为yyyyMMdd格式
MSS1113商户交易流水号格式错误格式应为6—32位字母或数字
MSS8011主机无此商户定义检查商户号、分行号是否正确
MSS2038非法商户:商户参数未定义检查商户数据是否正确
MSS1104请求时间延迟检查dateTime参数,不能早于服务器时间前30分钟
MSS3209该IP不允许发起此交易请检查商户管理系统配置参数
MSS1114原冻结交易商户订单号格式错误格式应为6—32位字母或数字
MSS3825查询失败具体失败原因参考报错信息
MSS3812查询交易不存在