对账文件下载API
1. 接口介绍
功能简述:
本接口用于商户下载对账文件,T+1日6:30以后可下载获取T日的对账文件。
2. 请求地址
测试环境URL:
http://merchserv.cmburl.cn/merchserv/BaseHttp.dll?GetDownloadURL
生产环境URL:
https://merchserv.netpay.cmbchina.com/merchserv/BaseHttp.dll?GetDownloadURL
3. 请求报文
报文的参数名:jsonRequestData,参数值JSON格式见下表:
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 |
date | String(8) | M | 查询日期,格式:yyyyMMdd | 20160624 |
transactType | String(4) | M | 交易类型,固定为“4001” | 4001 |
fileType | String(3) | M | 文件类型,固定为“YWT” | YWT |
messageKey | String(40) | M | 交易流水,合作方内部唯一流水 | 30899919311001620181017 |
请求示例:
json报文组织:
{ "version":"2.0", "charset":"UTF-8", "sign":"见签名处理章节", "signType":"SHA-256", "reqData": { "dateTime":"20160825113210", "branchNo":"0755", "merchantNo":"000054", "date":"20160116", "transactType":"4001", "fileType":"YWT", "messageKey":"30899919311001620181017" } }
表单组织:
<form action="请求地址" method="post"> <input type="hidden" name="jsonRequestData" value='以上json字符串' /> </form>
待签名字符串(未包含支付密钥):
branchNo=0755&date=20160116&dateTime=20160825113210&fileType=YWT&merchantNo=000054&messageKey=abc&transactType=4001
4. 响应报文
参数 | 类型(长度) | 必填 | 描述 | 示例 |
---|---|---|---|---|
version | String(3) | M | 固定为2.0 | 1.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 | M | 详细信息,请求处理失败时返回错误描述 | |
dateTime | String(14) | M | 响应时间。银行返回该数据的时间格式:yyyyMMddHHmmss | 20160623101430 |
downloadUrl | String | C | 查询成功时(rspCode=SUC0000)返回。文件的下载地址,必须在有效期内下载,过期则无法下载。 目前有效期是:获取链接时起的1小时内 | |
branchNo | String(4) | M | 商户分行号,4位数字 | 0755 |
merchantNo | String(6) | M | 商户号,6位数字 | 002346 |
date | String(8) | M | 商户订单日期,格式:yyyyMMdd | 20160625 |
响应示例:
正常json报文组织:
{ "version":"2.0", "charset":"utf-8", "sign":"见签名处理章节", "signType":"SHA-256", "rspData": { "rspCode":"SUC0000", "rspMsg":"", "dateTime":"20160825113210", "downloadUrl":"http://xyz.com/abc.txt", "date":"20160116", "branchNo":"0755", "merchantNo":"000123" } }
异常json报文组织:
{ "version":"2.0", "charset":"UTF-8", "sign":"见签名处理章节", "signType":"SHA-256", "rspData": { "rspCode":"MSS1017", "rspMsg":"商户号格式错误" } }
5. CSV文件字段信息
字段名称 | 长度 | 备注 |
---|---|---|
交易日期 | S(8,0) | 20180601 |
商户号 | A(10) | 0755630001 |
商户订单号 | A(32) | 扣款交易/冻结交易/付款交易的商户订单号 |
交易类型 | A(20) | 消费;退货;联机账户退货;付款;联机账户付款;冻结完成;预授权完成 |
交易金额 | S(13,2) | |
结账货币 | O(10) | 人民币;美元;港币 |
结账金额 | S(13,2) | 举例:0.01 |
费用金额 | S(13,2) | 举例:0.00 |
优惠金额 | S(13,2) | 举例:0.00 |
结算日期 | S(8,0) | 20180601 |
卡类型 | O(20) | 招行借记卡;招行信用卡;他行借记卡;他行信用卡; |
支付方式 | O(20) | 一网通支付 |
商户附加数据 | A(200) | |
银行流水 | A(64) | 处理支付/退货/付款/冻结完成交易的银行流水号 |
商户流水 | A(32) | 退货/冻结完成交易的商户流水号 |
预留字段 | A(256) |
6. 错误码
错误码 | 描述 | 解决方案 |
MSS9002 | 版本号错误 | Version固定为“1.0” |
MSS9003 | 签名算法错误 | 目前只支持“SHA-256” |
MSS9900 | 请求数据Json转换异常 | 校验并修改请求报文数据 |
MSS3413 | 请勿重复提交 | 请勿重复提交请求 |
MSS3115 | 无效交易类型 | 固定为“4001” |
MSS3116 | 无效文件类型 | 检查文件类型 |
MSS3117 | 无效交易流水 | 交易流水不能为空,且不能超过40位 |
MSS3411 | 签名错误 | 验证签名是否正确,请参考签名示例 |
USR0008 | 系统业务繁忙,稍后再试 | 超过最大并行请求处理数限制 |
MSS1016 | 分行号格式错误 | 分行号格式应为4位数字 |
MSS1017 | 商户号格式错误 | 商户号格式应为6位数字 |
MSS1019 | 操作员格式错误 | 操作员格式应为4位数字 |
MSS1022 | 订单日期或者时间格式错误 | 日期应为yyyyMMdd格式 时间应为yyyyMMddHHmmss格式 |
MSS8011 | 主机无此商户定义 | 检查商户号、分行号是否正确 |
MSS2038 | 非法商户:商户参数未定义 | 检查商户数据是否正确 |
7. FAQ
Q1. CSV文件字段信息中,S、A、O是什么意思?
S代表字段为数字。A代表字段为字符。O代表字段可以包含中英文。
Q2. 获取到正确的对账文件,格式应该是什么样子的?
请以实际获取到的文件为准,CSV文件名、文件内容可参考以下解压后的附件:
Q3. 支付方式是什么意思?
对于一网通主/被动支付交易,统一都返回“一网通支付”。除此之前,支付方式字段值还包括“微信支付、支付宝、银联、一网通免密支付(旧版本)”,与支付接口定制化功能和历史版本有关,默认不返回。