交易状态查询
1. 接口介绍
功能简述:
本接口用于商户主动查询“资金冻结交易、资金解冻交易、资金冻结完成扣款交易"的处理状态。
应用场景:
1、 当商户后台、网络、服务器等出现异常,或因为其他可能发生的未知原因,商户后台最终未接收到支付异步通知
2、 商户调用交易接口后,返回系统错误等情况
约束条件:
商户调用了冻结、解冻或冻结完成接口后,如果没收到同步应答或异步通知,可以通过本接口主动查询交易的处理状态。请注意:不要在调用冻结、解冻或冻结完成接口的同时,并发调用查询接口确认终态。
正常流程:
1、 报文合性校验
2、 报文参数校验
3、 同步返回交易处理状态
异常流程:
1、 商户在招行侧开通IP白名单控制,请求源IP不在IP白单中
2、 报文验签失败
3、 报文参数非法
4、 要查询的交易不存在
2. 请求地址
测试环境URL:
http://paytest.cmburl.cn:801/netpayment_directlink_nosession/QueryFreeze.do
生产环境URL:
https://merchserv.netpay.cmbchina.com/merchserv/QueryFreeze.do
3. 请求报文
请求报文参数 | 类型(长度) | 必填 | 描述 | 示例 |
---|---|---|---|---|
jsonRequestData | String | M | json格式的请求参数,详见jsonRequestData定义 |
jsonRequestData参数定义
参数名 | 类型(长度) | 必填 | 描述 | 示例 |
---|---|---|---|---|
version | String(3) | M | 固定为2.0 | 2.0 |
charset | String(8) | M | 编码格式,固定为UTF-8 | UTF-8 |
sign | String | M | 使用商户支付密钥对reqData内的数据进行签名 | |
signType | String | M | 固定为SHA-256 | SHA-256 |
reqData | 请求数据 | |||
dateTime | String(14) | M | 请求时间,商户发起该请求的时间,精确到秒。 格式: yyyyMMddHHmmss | 20160623101430 |
branchNo | String(4) | M | 商户分行号,4位数字 | 0755 |
merchantNo | String(6) | M | 商户号,6位数字 | 002346 |
type | String(3) | M | 查询类型
| FRZ |
date | String(8) | M | 商户冻结、解冻、冻结完成扣款交易日期YYYYMMDD | 20160623 |
merchantSerialNo | String(32) | M | 商户冻结、解冻、冻结完成扣款交易流水号 | 2016062310143088 |
当type=FRU或FRC时,需另外上送以下参数: | ||||
origDate | String(8) | C | 原商户资金冻结交易日期YYYYMMDD | 20160623 |
origOrderNo | String(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. 响应报文
参数名 | 类型(长度) | 必填 | 描述 | 示例 |
---|---|---|---|---|
version | String(3) | M | 固定为2.0 | 2.0 |
charset | String(8) | M | 参数编码,固定为UTF-8 | UTF-8 |
sign | String | M | 报文签名,使用商户支付密钥 对rspData内的数据进行验签 | |
signType | String | M | 签名算法,固定为SHA-256 | SHA-256 |
rspData | 应答数据 | |||
rspCode | String | M | 处理结果返回码
| SUC0000 |
rspMsg | String | C | 请求处理失败时返回错误原因描述 | |
dateTime | String(14) | M | 银行响应该请求的时间,格式yyyyMMddHHmmss | 20160623101430 |
branchNo | String(4) | M | 商户分行号,4位数字 | 0755 |
merchantNo | String(6) | M | 商户号,6位数字 | 002346 |
date | String(8) | M | 格式yyyyMMdd | 20160623 |
merchantSerialNo | String(32) | M | 商户交易流水号 | 2016062310143088 |
bankSerialNo | String(20) | M | 银行订单流水号 | 2016062310143099 |
origDate | String(8) | C | 原商户资金冻结交易日期YYYYMMDD | 20160623 |
origOrderNo | String(32) | C | 原商户资金冻结订单号 | 2016062310143011 |
currency | String(2) | M | 交易币种 | 10:人民币 |
amount | String | M | 交易金额,以元为单位,如10.01表示10元零1分 | 10.01 |
settleAmount | String | C | 结算金额(冻结完成交易查询时返回),以元为单位 | 10.01 |
fee | String | C | 手续费金额(冻结完成交易查询时返回),以元为单位 | 0.01 |
discountAmount | String | C | 优惠金额(冻结完成交易查询时返回),以元为单位 | 10.01 |
cardType | String(2) | O | 交易卡类型
| 02 |
bankDate | String(8) | M | 银行处理日期,格式yyyyMMdd | 20160623 |
bankTime | String(6) | M | 银行处理时间,格式HHmmss | 101430 |
orderstatus | String | M | 查询交易处理状态
| S |
unfreezeDate | String(8) | O | 到期自动解冻日期(冻结交易查询时返回) | 20210101 |
totalUnfreezeAmount | String | M | 原冻结交易累计已解冻金额: 1、自然日期小于unfreezeDate,该金额返回“原冻结交易商户累计发起已解冻的金额”,以元为单位,格式XXXX.XX 2、超过unfreezeDate后,该金额返回“原冻结交易的冻结金额减掉累计冻结完成扣款金额” | 10.01 |
totalPayAmount | String | M | 原冻结交易由商户发起累计冻结完成扣款金额,以元为单位,格式XXXX.XX | 10.01 |
restFreezeAmount | String | M | 原冻结交易剩余冻结金额: 1、自然日期小于unfreezeDate,该金额返回原冻结交易剩余冻结金额,以元为单位,格式XXXX.XX 2、超过unfreezeDate后,该金额返回0,代表商户不能再发起解冻或冻结完成扣款交易 | 10.01 |
以下字段联系招行配置控制参数后返回(默认不返回): | ||||
uniqueUserID | String(30) | C | 支付用户ID,由身份证+姓名生成(推荐使用) | UQwanCunLbp6cl1RbDFODrhLrAa48= |
expandUserID | String(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 | 查询交易不存在 |