优惠明细文件下载API
1. 接口介绍
功能简述:
本接口用于商户下载招行侧优惠明细的文件,包括优惠券批次号、优惠券优惠金额、立减活动编号、立减优惠金额等信息。T+1日14:00以后可下载获取T日交易的优惠明细文件。
2. 请求地址
测试环境URL:
http://paytest.cmburl.cn:801/netpayment_directlink_nosession/GetDownloadURL.do
生产环境URL:
https://merchserv.netpay.cmbchina.com/merchserv/GetDownloadURL.do
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(6) | M | 文件类型,固定为“YWT_YH” | YWT_YH |
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_YH", "messageKey":"30899919311001620181017" } }
表单组织:
<form action="请求地址" method="post"> <input type="hidden" name="jsonRequestData" value='以上json字符串' /> </form>
待签名字符串(未包含支付密钥):
branchNo=0755&date=20160116&dateTime=20160825113210&fileType=YWT_YH&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)返回。 | |
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":"https://xyz.com/abc", "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(15,2) | |
结账货币 | O(10) | 人民币;美元;港币 |
结账金额 | S(15,2) | 举例:0.01 |
费用金额 | S(15,2) | 举例:0.00 |
优惠金额 | S(15,2) | 举例:0.00 |
结算日期 | S(8,0) | 20180601 |
卡类型 | O(20) | 招行借记卡;招行信用卡;他行借记卡;他行信用卡; |
支付方式 | O(20) | 一网通支付 |
优惠券批次号 | A(14) | |
优惠券名称 | O(100) | |
优惠券优惠金额 | S(15,2) | 举例:0.00 |
优惠券所属机构 | A(6) | |
优惠券费用所属机构 | A(6) | |
优惠券活动负责人 | O(50) | |
优惠券活动负责人联系方式 | A(20) | |
立减活动编号 | A(9) | |
立减活动名称 | O(60) | |
立减优惠金额 | S(15,2) | 举例:0.00 |
立减活动所属机构 | A(6) | |
立减活动费用所属机构 | A(6) | |
立减活动负责人 | O(50) | |
立减活动负责人联系方式 | A(20) | |
商户附加数据 | A(200) | |
银行流水 | A(64) | 处理支付/退货/付款/冻结完成交易的银行流水号 |
商户流水 | A(32) | 退货/冻结完成交易的商户流水号 |
预留字段 | A(256) |
6. 错误码
错误码 | 描述 | 解决方案 |
MSS9900 | 请求数据Json转换异常 | 校验并修改请求报文数据 |
MSS3413 | 请勿重复提交 | 请勿重复提交请求 |
MSS3115 | 无效交易类型 | 固定为“4001” |
MSS3116 | 无效文件类型 | 检查文件类型,固定为"YWT_YH" |
MSS3117 | 无效交易流水 | 交易流水不能为空,且不能超过40位 |
MSS3411 | 签名错误 | 验证签名是否正确,请参考签名示例 |
USR0008 | 系统业务繁忙,稍后再试 | 超过最大并行请求处理数限制 |
MSS1016 | 分行号格式错误 | 分行号格式应为4位数字 |
MSS1017 | 商户号格式错误 | 商户号格式应为6位数字 |
MSS1022 | 订单日期或者时间格式错误 | 日期应为yyyyMMdd格式 时间应为yyyyMMddHHmmss格式 |
MSS8011 | 主机无此商户定义 | 检查商户号、分行号是否正确 |
MSS2038 | 非法商户:商户参数未定义 | 检查商户数据是否正确 |
PMS5402 | 查询为空,无法获取url | 获取账单失败 |
7. FAQ
Q1. CSV文件字段信息中,S、A、O是什么意思?
S代表字段为数字。A代表字段为字符。O代表字段可以包含中英文。
Q2. 获取到正确的文件,格式应该是什么样子的?
以每个商户实际获取到的为准,格式可参考以下附件:
DAILY_YH_0755000054_20201215.zip
Q3. 获取文件中没有优惠明细数据?
支持支付结算日期在2020年12月15日后的交易展示优惠明细数据,包含优惠券批次号、立减活动编号等信息。