下载交易账单

应用场景

商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和微信侧数据不一致,通过对账单核对后可校正支付状态。

注意:

1、微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中,跟原支付单订单号一致;

2、微信在次日9点启动生成前一天的对账单,建议商户10点后再获取;

3、对账单中涉及金额的字段单位为“元”。

4、对账单接口只能下载三个月以内的账单。

5、对账单是以商户号维度来生成的,如一个商户号与多个appid有绑定关系,则使用其中任何一个appid都可以请求下载对账单。对账单中的appid取自交易时候提交的appid,与请求下载对账单时使用的appid无关。

6、小微商户不单独提供对账单下载,如有需要,可在调取【下载对账单】API接口时不传sub_mch_id,获取服务商下全量特约商户(包括小微商户和非小微商户)的对账单。

7、自2018年起入驻的商户默认是开通免充值券后的结算对账单。

接口链接

https://api.mch.weixin.qq.com/pay/downloadbill

是否需要证书

不需要。

请求参数

字段名 变量名 必填 类型 示例值 描述
服务商的APPID appid String(32) wx8888888888888888 服务商商户的APPID
商户号 mch_id String(32) 1900000109 微信支付分配的商户号
子商户公众账号ID sub_appid String(32) wx8888888888888888 微信分配的子商户公众账号ID
子商户号 sub_mch_id String(32) 1900000109 微信支付分配的子商户号,如需下载指定的子商户号对账单,则此参数必传。
随机字符串 nonce_str String(32) 5K8264ILTKCH16CQ2502SI8ZNMTM67VS 随机字符串,不长于32位。推荐随机数生成算法
签名 sign String(32) C380BEC2BFD727A4B6845133519F3AD6 签名,详见签名生成算法
签名类型 sign_type String(32) HMAC-SHA256 签名类型,目前支持HMAC-SHA256和MD5,默认为MD5
对账单日期 bill_date String(8) 20140603 下载对账单的日期,格式:20140603
账单类型 bill_type String(8) ALL

ALL,返回当日所有订单信息,默认值

SUCCESS,返回当日成功支付的订单

REFUND,返回当日退款订单

RECHARGE_REFUND,返回当日充值退款订单

压缩账单 tar_type String GZIP 非必传参数,固定值:GZIP,返回格式为.gzip的压缩包账单。不传则默认为数据流形式。

<xml>
   <appid>wx2421b1c4370ec43b</appid>
   <bill_date>20141110</bill_date>
   <bill_type>ALL</bill_type>
   <mch_id>10000100</mch_id>
   <nonce_str>21df7dc9cd8616b56919f20d9f679233</nonce_str>
   <sign>332F17B766FC787203EBE9D6E40457A1</sign>
</xml>

返回结果

失败时,返回以下字段

字段名 变量名 必填 类型 示例值 描述
返回状态码 return_code String(16) FAIL FAIL
错误码描述 return_msg String(128) 签名失败

返回信息,如非空,为错误原因

如:签名失败 等。

错误码 error_code String(16) 20002

失败错误码,详见错误码列表

交易账单格式说明


1. 交易账单介绍

微信支付每天提供前一天的交易账单文件,用于商户核对订单、退款、营销、手续费等信息。账单内的数据包括:

(1)当天支付成功的订单,下单成功单用户未支付的订单不会出账。

(2)当天发起退款成功的退款单,退款发起成功就会出账,出账后退款状态不会更新。如果需要获取最新退款状态,请使用查询退款API查询。

微信支付提供了3份不同类型的账单文件:

• ALL,包含了当天支付成功的订单和发起成功的退款单

• SUCCESS,仅包含支付成功的订单

• REFUND,仅包含发起成功的退款单

2. 交易账单的文件格式

交易账单文件内包含:明细数据表头、明细数据内容、汇总数据表头、汇总数据四个部分,每个字段使用英文逗号 , 间隔,明细数据内容每个字段前会增加1个字符 ` 用于避免获取的内容被excel展示为科学计数法的格式、丢失数据细节。3份不同类型的账单文件字段内容略有差异。

2.1. ALL类型账单文件具体字段

字段名 描述 示例值
明细数据
交易时间 指该笔交易的支付成功时间或发起退款成功时间(注:不是退款成功时间),格式为YYYY-MM-DD HH:MM:SS 2015-01-01 10:00:00
公众账号ID 发起该笔交易时使用的appid,appid是由微信给公众号或app等分配的唯一标识 wxab8acb865bb11234
商户号 发起该笔交易下单的微信支付商户号,8~10位数字 1234567890
特约商户号 如果是普通受理模式下的交易,展示特约商户的商户号,8~10位数字
如果是普通直连模式交易,则展示成数字0
1234567890
设备号 对应在下单时传入的device_info字段,没填写则留空 casher001
微信订单号 微信支付为该笔订单(或该笔退款对应的订单)分配的订单号 4200000008201712143733500001
商户订单号 商户传入的该笔订单(或该笔退款对应的订单)的商户订单号,对应下单接口里的out_trade_no字段 outtradeno001
用户标识 微信为支付用户在公众账号ID(appid)下分配的唯一标识(openid) testxt08c-XB5-QD208X1Aid0Cbs
交易类型 该笔订单(或该笔退款单对应的订单)的类型,使用英文缩写展示,包括但不限于(后续可能新增):
MICROPAY,付款码支付
JSAPI,JSAPI支付、小程序支付
NATIVE,Native支付
APP,APP支付
FACE,刷脸支付
NATIVE
交易状态 标识该笔明细数据的类型:
SUCCESS,支付成功,说明该行数据为一笔支付成功的订单
REFUND,转入退款,说明该行数据为一笔发起退款成功的退款单
REVOKED,已撤销,说明该行数据为一笔在用户支付成功后发起撤销的退款单
SUCCESS
付款银行 用户支付时使用的付款方式,包括但不限于(后续可能新增):
XXX_CREDIT,用户使用了XXX银行的一张信用卡付款
XXX_DEBIT,用户使用了XXX银行的一张储蓄卡付款
OTHERS,用户使用了零钱/零钱通等其他付款方式
CMB_CREDIT
货币种类 货币类型,符合ISO 4217标准的三位字母代码 CNY
应结订单金额 该笔订单参与计费的应结算金额(=订单金额-用户使用的免充值券金额),如果该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位 8.88
代金券金额 该笔订单中使用的微信支付代金券金额(包括充值券和免充值券),如果未使用代金券、或该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位 0.88
微信退款单号 微信支付为该笔退款分配的退款单号,如果该行数据为订单(交易状态SUCCESS)则展示0 50401010122021000000038202001
商户退款单号 商户发起退款时填入的商户退款单号,如果该行数据为订单(交易状态SUCCESS)则展示0 refundno001
退款金额 该笔退款单参与计费的应结算金额(申请退款金额-免充值券退款金额),如果该行数据为订单则展示为0.00,非负数、单位元,保留到小数点后2位 6.66
充值券退款金额 退款金额中包含的充值券退款金额,如果该行数据为订单或没有充值券退款则展示为0.00,非负数、单位元,保留到小数点后2位 0.66
退款类型 ORIGINAL—原路退款
BALANCE—转退到用户的微信支付零钱
如果该行数据为订单(交易状态SUCCESS)则留空
ORIGINAL
退款状态 生成账单文件时该笔退款的状态、出账后不会更新,如果该行数据为订单(交易状态SUCCESS),则留空
SUCCESS,退款成功
PROCESSING,退款处理中
FAIL,退款失败
CHANGE,退款异常
SUCCESS
商品名称 商户传入的该笔订单(或该笔退款对应的订单)的商品名称,对应下单接口里的body字段 零食
商户数据包 商户传入的该笔订单(或该笔退款对应的订单)的商户数据包,对应下单接口里的attach字段,不传时留空 交易收款
手续费 该笔订单/退款对应的手续费金额,订单对应正数、退款对应负数,单位元,保留小数点后2位 0.01
费率 该笔交易计费所使用的费率,百分数 0.60%
订单金额 该笔订单的金额,包括用户支付金额、充值券金额、免充值券金额,如果该行数据为退款或撤销则填0.00,单位元,保留到小数点后2位 9.76
申请退款金额 商户发起退款的金额,包括退给用户的金额、充值券退款金额、免充值券退款金额,如果该行数据订单则填0.00,单位元,保留到小数点后2位 6.66
费率备注 对计费费率的补充说明,如入驻结算规则ID、优惠费率活动ID等,可为空 726
汇总数据
总交易单数 该份账单内明细数据的笔数 200
应结订单总金额 账单内所有应结订单金额字段之和,保留小数点后2位 888.00
退款总金额 账单内所有退款金额字段之和,保留小数点后2位 666.00
充值券退款总金额 账单内所有充值券退款金额字段之和,保留小数点后2位 6.60
手续费总金额 账单内所有交易手续费字段之和,保留小数点后2位 10.00
订单总金额 账单内所有交易订单金额字段之和,保留小数点后2位 976.00
申请退款总金额 账单内所有申请退款金额字段之和,保留小数点后2位 666.00

2.2. SUCCESS和REFUND账单

SUCCESS和REFUND账单的字段和ALL账单内略有不同

SUCCESS账单字段:交易时间,公众账号ID,商户号,特约商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,应结订单金额,代金券金额,商品名称,商户数据包,手续费,费率,订单金额,费率备注

REFUND账单字段:交易时间,公众账号ID,商户号,特约商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,应结订单金额,代金券金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款金额,充值券退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率,订单金额,申请退款金额,费率备注

2.3. 特殊字符转义

账单处理过程会对商品名称、商户数据包、设备号等商户自定义字段进行特殊字符转义,具体规则包括:

'转换成为\'

"转换成为\"

`转换成为\`

,转换成为\ (\+空格)

\r转换成为\\r

\t转换成为\\t

2.4. 补充说明

少部分商户目前的账单格式停留在历史早期版本,具体表现为:没有应结算订单金额字段、对应的是总金额字段,没有代金券金额字段、对应的是企业红包金额字段。如需调整为最新格式的账单,可以通过在产品中心中开通免充值优惠券功能,次日开始的账单格式即会完成变更。

3. 账单样例

《ALL.xlsx》《REFUND.xlsx》《SUCCESS.xlsx》

错误码

错误码 名称 描述 原因 解决方案
100 SYSTEMERROR 下载失败 系统超时 请尝试再次查询。
100 Network Traffic Limit 网络流量限制 当前系统请求繁忙 请尝试再次查询
20003 SYSTEMERROR 下载失败 系统超时 请尝试再次查询。
20001 sign error 签名错误 请求参数未按要求进行填写 签名错误,请重新检查参数和签名密钥是否正确
nonce_str too long 参数nonce_str错误 请求参数未按要求填写 参数nonce_str长度超长
invalid tar_type, Only GZIP supported 参数tar_type错误 请求参数未按指引进行填写 请重新检查参数invalid tar_typ是否正确
invalid bill_type 参数bill_type错误 请求参数未按指引进行填写 请重新检查参数bill_type是否正确
invalid bill_date 参数bill_date错误 请求参数未按指引进行填写 请重新检查参数bill_date是否符合要求
require POST method 请求方式错误 请求方式不符合要求 请求检查参数请求方式是否为post
empty post data 请求报文错误 请求报文为空 请重新检查请求报文是否正确
data format error 参数格式错误 请求参数要求为xml格式 请重新检查请求参数格式是否为xml
missing parameter 缺少参数 有必传的参数未上传 请重新检查是否所有必传参数都上传了,且不为空
invalid appid appid错误 请求参数appid有误 请重新检查参数appid是否正确
invalid parameter 参数错误 有未知的请求参数 请重新检查是否所有参数都与文档相符
sub_mch not allow 特约商户号权限错误 无该特约商户账单的下载权限 请检查特约商户号是否正确。若是小微商户,可不传sub_mch_id以获取服务商下全量特约商户的账单
20002 No Bill Exist 账单不存在 当前商户号没有已成交的订单,不生成对账单 请检查当前商户号在指定日期内是否有成功的交易。
Bill Creating 账单未生成 当前商户号没有已成交的订单或对账单尚未生成 请先检查当前商户号在指定日期内是否有成功的交易,如指定日期有交易则表示账单正在生成中,请在上午10点以后再下载。
20007 当前商户号账单API权限已经关闭 当前商户号账单API权限已经关闭 当前商户号账单API权限已经关闭 当前商户号账单API权限已经关闭,请联系微信支付解决
20100 system error 下载失败 系统超时 请尝试再次查询。