---
url: "https://pay.weixin.qq.com/doc/v2/partner/4011936649.md"
title: "下载交易账单"
doc_id: 4011936649
---

>更新时间：2024.11.13

## 应用场景

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

注意：

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位。推荐[随机数生成算法](https://pay.weixin.qq.com/doc/v2/partner/4011985884.md) |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名，详见[签名生成算法](https://pay.weixin.qq.com/doc/v2/partner/4011985884.md) |
| 签名类型 | sign\_type | 否 | String(32) | HMAC-SHA256 | 签名类型，目前支持HMAC-SHA256和MD5，默认为MD5 |
| 对账单日期 | bill\_date | 是 | String(8) | 20140603 | 下载对账单的日期，格式：20140603 |
| 账单类型 | bill\_type | 否 | String(8) | ALL | ALL，返回当日所有订单信息，默认值<br>SUCCESS，返回当日成功支付的订单<br>REFUND，返回当日退款订单<br>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) | 签名失败 | 返回信息，如非空，为错误原因<br>如：签名失败 等。 |
| 错误码 | error\_code | 否 | String(16) | 20002 | 失败错误码，详见错误码列表 |

## 交易账单格式说明

### 1. 交易账单介绍

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

（1）当天支付成功的订单，下单成功单用户未支付的订单不会出账。

（2）当天发起退款成功的退款单，退款发起成功就会出账，出账后退款状态不会更新。如果需要获取最新退款状态，请使用[查询退款API](https://pay.weixin.qq.com/doc/v2/partner/4011936648.md)查询。

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

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


- SUCCESS，仅包含支付成功的订单


- REFUND，仅包含发起成功的退款单


### 2. 交易账单的文件格式

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

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

| 字段名 | 描述 | 示例值 |
| --- | --- | --- |
| 明细数据 | 明细数据 | 明细数据 |
| 交易时间 | 指该笔交易的支付成功时间或商户退款受理成功时间，格式为YYYY-MM-DD HH:MM:SS，具体规则详见[账单数据时间介绍](https://pay.weixin.qq.com/doc/v3/partner/4013080592.md#6%E3%80%81%E8%B4%A6%E5%8D%95%E6%95%B0%E6%8D%AE%E6%97%B6%E9%97%B4) | 2015-01-01 10:00:00 |
| 公众账号ID | 发起该笔交易时使用的appid，appid是由微信给公众号或app等分配的唯一标识<br>注意：如果下单时有传sub\_appid，此处是sub\_appid的参数值，没传则是appid的值<br>对应查询订单接口的应答参数“appid”字段或“sub\_appid”字段 | wxab8acb865bb11234 |
| 商户号 | 发起该笔交易下单的微信支付商户号，8~10位数字<br>对应查询订单接口和查询退款接口的请求参数“mch\_id”字段 | 1234567890 |
| 特约商户号 | 如果是普通受理模式下的交易，展示特约商户的商户号，8~10位数字<br>如果是普通直连模式交易，则展示成数字0<br>对应查询订单接口和查询退款接口的请求参数“sub\_mch\_id”字段 | 1234567890 |
| 设备号 | 对应在下单时传入的device\_info字段，没填写则留空<br>对应查询订单接口中的应答参数“device\_info”字段，字段可能被转义，具体规则见[特殊字符转义](https://pay.weixin.qq.com/doc/v2/partner/4011936649.md#2.3.-%E7%89%B9%E6%AE%8A%E5%AD%97%E7%AC%A6%E8%BD%AC%E4%B9%89)[表](https://pay.weixin.qq.com/doc/v2/partner/4011936649.md#2.3.-%E7%89%B9%E6%AE%8A%E5%AD%97%E7%AC%A6%E8%BD%AC%E4%B9%89) | casher001 |
| 微信订单号 | 微信支付为该笔订单（或该笔退款对应的订单）分配的订单号<br>对应查询订单接口和查询退款接口的应答参数“transaction\_id”字段 | 4200000008201712143733500001 |
| 商户订单号 | 商户传入的该笔订单（或该笔退款对应的订单）的商户订单号，对应下单接口里的out\_trade\_no字段<br>对应查询订单接口和查询退款接口的应答参数“out\_trade\_no”字段 | outtradeno001 |
| 用户标识 | 微信为支付用户在公众账号ID(appid)下分配的唯一标识(openid)<br>注意：如果下单时有传sub\_openid，此处是sub\_openid的参数值，没传则是openid的值<br>对应查询订单接口中的应答参数“openid”字段或“sub\_openid”字段 | testxt08c-XB5-QD208X1Aid0Cbs |
| 交易类型 | 该笔订单（或该笔退款单对应的订单）的类型，使用英文缩写展示，包括但不限于（后续可能新增）：<br>MICROPAY，付款码支付<br>JSAPI，JSAPI支付、小程序支付<br>NATIVE，Native支付<br>APP，APP支付<br>FACE，刷脸支付<br>对应查询订单接口中的应答参数“trade\_type”字段 | NATIVE |
| 交易状态 | 标识该笔明细数据的类型：<br>SUCCESS，支付成功，说明该行数据为一笔支付成功的订单<br>REFUND，转入退款，说明该行数据为一笔发起退款成功的退款单<br>REVOKED，已撤销，说明该行数据为一笔在用户支付成功后发起撤销的退款单 | SUCCESS |
| 付款银行 | 用户支付时使用的付款方式，包括但不限于（后续可能新增），详见[银行类型对照表](https://pay.weixin.qq.com/doc/v3/partner/4012082814.md)：<br>XXX\_CREDIT，用户使用了XXX银行的一张信用卡付款<br>XXX\_DEBIT，用户使用了XXX银行的一张储蓄卡付款<br>OTHERS，用户使用了零钱/零钱通等其他付款方式 | CMB\_CREDIT |
| 货币种类 | 货币类型，符合ISO 4217标准的三位字母代码 | CNY |
| 应结订单金额 | 该笔订单参与计费的应结算金额（=订单金额-用户使用的免充值券金额），如果该行数据为退款或撤销则展示0.00，单位元，保留到小数点后2位<br>对应查询订单接口和查询退款接口的应答参数“settlement\_total\_fee”字段 | 8.88 |
| 代金券金额 | 该笔订单中使用的微信支付代金券金额（包括充值券和免充值券），如果未使用代金券、或该行数据为退款或撤销则展示0.00，单位元，保留到小数点后2位<br>对应查询订单接口中的应答参数“coupon\_fee”字段 | 0.88 |
| 微信退款单号 | 微信支付为该笔退款分配的退款单号，如果该行数据为订单（交易状态SUCCESS）则展示0<br>对应查询退款接口中的应答参数“refund\_id”字段 | 50401010122021000000038202001 |
| 商户退款单号 | 商户发起退款时填入的商户退款单号，如果该行数据为订单（交易状态SUCCESS）则展示0<br>对应查询退款接口中的应答参数“out\_refund\_no”字段 | refundno001 |
| 退款金额 | 该笔退款单参与计费的应结算金额（申请退款金额-免充值券退款金额），如果该行数据为订单则展示为0.00，非负数、单位元，保留到小数点后2位<br>对应查询退款接口中的应答参数“settlement\_refund\_fee”字段 | 6.66 |
| 充值券退款金额 | 退款金额中包含的充值券退款金额，如果该行数据为订单或没有充值券退款则展示为0.00，非负数、单位元，保留到小数点后2位 | 0.66 |
| 退款类型 | ORIGINAL—原路退款<br>BALANCE—转退到用户的微信支付零钱<br>PLATFORM-ORIGINAL—平台退款，原路退款<br>PLATFORM-BALANCE—平台退款，转退到用户的微信支付零钱<br>如果该行数据为订单（交易状态SUCCESS）则留空<br>对应查询退款接口中的应答参数“refund\_channel”字段 | ORIGINAL |
| 退款状态 | 生成账单文件时该笔退款的状态、出账后不会更新，如果该行数据为订单（交易状态SUCCESS），则留空<br>SUCCESS，退款成功<br>PROCESSING，退款处理中<br>FAIL，退款失败<br>CHANGE，退款异常<br>对应查询退款接口中的应答参数“refund\_status”字段 | SUCCESS |
| 商品名称 | 商户传入的该笔订单（或该笔退款对应的订单）的商品名称，对应下单接口里的“body”字段 | 零食 |
| 商户数据包 | 商户传入的该笔订单（或该笔退款对应的订单）的商户数据包，对应下单接口里的“attach”字段，不传时留空 | 交易收款 |
| 手续费 | 该笔订单/退款对应的手续费金额，订单对应正数、退款对应负数，单位元，保留小数点后2位 | 0.01 |
| 费率 | 该笔交易计费所使用的费率，百分数 | 0.60% |
| 订单金额 | 该笔订单的金额，包括用户支付金额、充值券金额、免充值券金额，如果该行数据为退款或撤销则填0.00，单位元，保留到小数点后2位<br>对应查询订单接口和查询退款接口的应答参数“total\_fee”字段 | 9.76 |
| 申请退款金额 | 商户发起退款的金额，包括退给用户的金额、充值券退款金额、免充值券退款金额，如果该行数据订单则填0.00，单位元，保留到小数点后2位<br>对应查询退款接口中的应答参数“refund\_fee”字段 | 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. 特殊字符转义

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

| 原始特殊字符<br>Unicode | 含义 | 订单转义<br>Unicode | 含义 | 退款单转义<br>Unicode | 含义 |
| --- | --- | --- | --- | --- | --- |
| `\u005c` | \ | `\u005c\u005c` | \\\ | `\u005c\u005c` | \\\ |
| `\u0027` | ' | `\u005c\u0027` | \\' | `\u0027` | ' |
| `\u0022` | " | `\u005c\u0022` | \\" | `\u005c\u0022` | \\" |
| `\u0060` | \` | `\u005c\u0060` | \\\` | `\u005c\u0031\u0034\u0030` | \\140 |
| `\u002c` | , | `\u005c\u0020` | \\空格 | `\u005c\u0020` | \\空格 |
| `\u000a` | 换行符(LF) | `\u005c\u006e` | \\n | `\u005c\u006e` | \\n |
| `\u000d` | 回车符(CR) | `\u005c\u0072` | \\r | `\u005c\u0072` | \\r |
| `\u0009` | 制表符(HT) | `\u005c\u0074` | \\t | `\u005c\u0074` | \\t |
| `\ue000` | 不可见字符(\\xee\\x80\\x80) | `\u005c\u0020` | \\空格 | `\u005c\u0020` | \\空格 |
| `\u001a` | 控制字符SUB(\\032) | `\u005c\u001a` | \\控制字符SUB | `\u005c\u001a` | \\控制字符SUB |

#### 2.4. 补充说明

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

### 3. 账单样例

[ALL.xlsx](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/attachment/ee92583444d28eb74649be6e6eaa4b40/ALL.xlsx)[REFUND.xlsx](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/attachment/1c05d9a582c5f0ed6acbc4623e44eddb/REFUND.xlsx)[SUCCESS.xlsx](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/attachment/1745f48f3b1af340b2cb1495261fa0db/SUCCESS.xlsx)

## 错误码

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