APP支付

优惠明细文件下载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参数定义

参数名类型(长度)必填描述示例
versionString(3)M固定为2.02.0
charsetString(8)M参数编码,固定为“UTF-8”UTF-8
signStringM报文签名,对reqData内的数据进行签名
signTypeStringM固定为SHA-256SHA-256
reqData请求数据


dateTimeString(14)M请求时间,商户发起该请求的时间,精确到秒。
格式:yyyyMMddHHmmss
20160623101430
branchNoString(4)M商户分行号,4位数字0755
merchantNoString(6)M商户号,6位数字002346
dateString(8)M查询日期,格式:yyyyMMdd20160624
transactTypeString(4)M交易类型,固定为“4001”4001
fileTypeString(6)M文件类型,固定为“YWT_YH”YWT_YH
messageKeyString(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. 响应报文

参数类型(长度)必填描述示例
versionString(3)M固定为2.01.0
charsetString(8)M编码格式,固定为UTF-8(默认)UTF-8
signStringM报文签名,使用商户支付密钥对rspData内的数据进行验签
signTypeStringM签名算法,固定为”SHA-256”SHA-256
rspData应答数据


rspCodeStringM处理结果
SUC0000:请求处理成功
其他:请求处理失败
SUC0000
rspMsgStringM详细信息,请求处理失败时返回错误描述
dateTimeString(14)M响应时间。银行返回该数据的时间格式:yyyyMMddHHmmss20160623101430
downloadUrlStringC查询成功时(rspCode=SUC0000)返回。
branchNoString(4)M商户分行号,4位数字0755
merchantNoString(6)M商户号,6位数字002346
dateString(8)M商户订单日期,格式:yyyyMMdd20160625

响应示例:

正常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日后的交易展示优惠明细数据,包含优惠券批次号、立减活动编号等信息。