查询入账明细API
1. 接口介绍
功能简述:
商户可以通过本接口,查询对应日期的交易明细数据。T+1日凌晨0:00以后,可查询T日的交易明细。
正常流程:
1、首次查询
2、根据返回的续传标志,继续查询
3、直至查询结束
异常流程:
1、尚未对账
2、无效续传键值
2. 请求地址
测试环境URL:
http://merchserv.cmburl.cn/merchserv/BaseHttp.dll?QueryAccountListV2
生产环境URL:
https://merchserv.netpay.cmbchina.com/merchserv/BaseHttp.dll?QueryAccountListV2
3. 请求报文
报文的参数名:jsonRequestData,参数值JSON格式见下表:
jsonRequestData参数定义
参数 | 类型(长度) | 必填 | 描述 | 示例 |
version | String(3) | M | 接口版本号,固定为“3.0” | 3.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 | 20160623120100 |
branchNo | String(4) | M | 商户分行号,4位数字 | 0755 |
merchantNo | String(6) | M | 商户号,6位数字 | 000054 |
date | String(8) | M | 查询日期,格式:yyyyMMdd | 20160624 |
operatorNo | String | M | 操作员号,商户结账系统的操作员(可固定为9999)。 | 9999 |
nextKeyValue | String(186) | C | 续传键值,首次查询填“空”; 后续查询,按应答报文中返回的nextKeyValue值原样传入。 | HH00012016050309493316250308400000000010 |
请求示例
1.json报文组织:
{ "version":"2.0", "charset":"UTF-8", "sign":"见签名处理章节", "signType":"SHA-256", "reqData": { "dateTime":"20160825113210", "branchNo":"0755", "merchantNo":"000054", "date":"20160116", "operatorNo":"9999", "nextKeyValue":"" } }
2.表单组织:
<form action="请求地址" method="post" /> <input type="hidden" name="jsonRequestData" value='以上json字符串' /> <input type="hidden" name="charset" value='UTF-8' /> </form>
3.待签名字符串示例(未包含支付密钥):
branchNo=0755&date=20160116&dateTime=20160825113210&merchantNo=000054&nextKeyValue=&operatorNo=9999
4. 响应报文
参数 | 类型(长度) | 必填 | 描述 | 示例 |
version | String(3) | M | 接口版本号, 1.0:代表无签名版本,对应请求报文1.0; 2.0:代表有签名版本,对应请求报文2.0、3.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:请求处理成功 其他:请求处理失败 | SUC0000 |
rspMsg | String | C | 详细信息,请求处理失败时返回错误描述 | |
dateTime | String(14) | M | 响应时间。银行返回该数据的时间 格式:yyyyMMddHHmmss | 20160624121212 |
hasNext | String(1) | M | 续传标志,Y:有续传(还有更多记录); N:无续传(记录已返回完毕)。 | Y |
nextKeyValue | String(40) | C | 续传键值,当hasNext=Y时必传。 | |
dataCount | String | M | 本次查询返回条数 | 200 |
dataList | String | 记录数据,每笔记录一行,行之间以\r\n分隔。 第一行为表头; 从第二行起为数据记录; 行内的参数以逗号和`符号分隔(`为标准键盘1 左边键的字符),字段顺序与表头一致。 数据记录定义如下: | branchNo,`merchantNo,`date\r\n0755,`000054,`20160624\r\n | |
branchNo | String(4) | M | 商户分行号,4位数字 | 0755 |
merchantNo | String(6) | M | 商户号,6位数字 | 000054 |
date | String(8) | M | 交易日期,格式:yyyyMMdd | 20160625 |
orderNo | String(32) | M | 商户订单号(扣款交易/冻结交易/付款交易的商户订单号) | 9999000001 |
merchantSerialNo | String(32) | M | 商户流水号(退款/冻结完成交易的商户流水号) | 9999000001 |
bankSerialNo | String(20) | M | 银行交易流水号(处理支付/退货/付款/冻结完成交易的银行流水号) | 20160624 |
currency | String(2) | M | 交易币种,固定为:“10” | 10 |
payMethod | String(2) | M | 支付方式, 01:一网通支付 | 01 |
transType | String(1) | M | 交易类型, S:支付; R:退款; M:联机账户退款; F:付款; L:联机账户付款; D:冻结完成 | S |
orderAmount | String(14) | M | 订单金额,格式:xxxx.xx | |
settleAmount | String(14) | M | 结算金额,格式:xxxx.xx | 0.01 |
discountAmount | String(14) | O | 优惠金额,格式:xxxx.xx | 0.00 |
Fee | String | M | 费用金额,格式:xxxx.xx | 0.01 |
transDate | String(8) | M | 交易日期,格式:yyyyMMdd | 20160624 |
transTime | String(6) | M | 交易时间,格式:HHmmss | 121201 |
bankDate | String(8) | M | 结算日期,格式:yyyyMMdd | 20160624 |
bankTime | String(6) | M | 结算时间,格式:HHmmss | 121201 |
cardType | String | O | 卡类型, 02:本行借记卡; 03:本行贷记卡; 08:他行借记卡; 09:他行贷记卡; WXLQ:微信零钱(微信支付场景用) | 02 |
merchantPara | String(100) | O | 商户自定义参数,对应商户在支付接口中传送的payNoticePara参数,和在退款接口中传送的desc参数,超过100字节自动截断。 |
响应示例
1.正常json报文组织:
{ "version":"2.0", "charset":"utf-8", "sign":"见签名处理章节", "signType":"SHA-256", "rspData":{ "rspCode":"SUC0000", "rspMsg":"", "dateTime":"20160825113210", "hasNext":"N", "nextKeyValue":"2016011611351816272197800000000010", "dataCount":"2", "dataList":"branchNo,`merchantNo,`date,`orderNo,`bankSerialNo,`currency,`transType,`orderAmount,`settleAmount,`discountAmount,`fee,`transDate,`transTime,`bankDate,`bankTime,`cardType,`merchantPara\r\n0755,`000054,`20160721,`9999000125,`16272100600000000010,`10,`S,`21.00,`17.46,`3.54,`1.75,`20160721,`084259,`20160116,`084259,`02,` \r\n0755,`000054,`20160720,`9999000501,`16272085700000000010,`10,`S,`0.01,`0.01,`0.00,`0.00,`20160720,`173045,`20160116,`173045,`07,`para1 " } }
2.异常json报文组织:
{ "version":"2.0", "charset":"UTF-8", "sign":"见签名处理章节", "signType":"SHA-256", "rspData":{ "rspCode":"MSS3107", "rspMsg":" PAY3107.无效续传键值" } }
5. 错误码
错误码 | 描述 | 解决方案 |
MSS9002 | 版本号错误 | Version固定为“1.0” |
MSS9003 | 签名算法错误 | 目前只支持“SHA-256” |
MSS9900 | 请求数据Json转换异常 | 校验并修改请求报文数据 |
MSS3411 | 签名错误 | 验证签名是否正确,请参考签名示例 |
USR0008 | 系统业务繁忙,稍后再试 | 超过最大并行请求处理数限制 |
MSS1016 | 分行号格式错误 | 分行号格式应为4位数字 |
MSS1017 | 商户号格式错误 | 商户号格式应为6位数字 |
MSS1019 | 操作员格式错误 | 操作员格式应为4位数字 |
MSS1022 | 订单日期或者时间格式错误 | 日期应为yyyyMMdd格式 时间应为yyyyMMddHHmmss格式 |
MSS8011 | 主机无此商户定义 | 检查商户号、分行号是否正确 |
MSS2038 | 非法商户:商户参数未定义 | 检查商户数据是否正确 |
MSS3808 | 查询失败 | 具体失败原因参考报错信息 |
6. FAQ
Q1. 续传键值的用途是什么?应该如何使用续传键值?
对于批量查询的API,如果查询结果记录数较多,一次通讯可能无法返回所有的记录数,这个时候我们采用续传键值的方法实现翻页查询。
首次查询续传键值填空字符串,此时银行系统会从头开始返回查询结果。商户收到返回报文后,应当判断续传标志hasNext,如果hasNext=Y
则时表示银行还有数据返回给商户,商户下次查询取前一返回报文的nextKeyValue值原样发送给银行,银行会从上一次返回结果处继续返回结果记录,直至hasNext=N
表示查询完毕。
Q2. 返回交易类型M,是什么意思?
“M:联机账户退款”,是指商户开通了“联机从对公结算账户扣取退款交易金额”的超额退款功能。请注意:对账明细中,对应交易类型为M的退款交易,不纳入一网通支付T+1与商户清算的流程中,仅供商户查询使用。