# 下载对账单

> 使用本接口需要开启[开放接口服务](/minigame/dev/wxcloudrun/src/guide/weixin/open)

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

1. 微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中，跟原支付单订单号一致；
2. 微信在次日 9 点启动生成前一天的对账单，建议商户 10 点后再获取；
3. 对账单中涉及金额的字段单位为“元”。
4. 对账单接口只能下载三个月以内的账单。
5. 对账单是以商户号纬度来生成的，如一个商户号与多个 appid 有绑定关系，则使用其中任何一个 appid 都可以请求下载对账单。对账单中的 appid 取自交易时候提交的 appid，与请求下载对账单时使用的 appid 无关。
6. 小微商户不单独提供对账单下载，如有需要，可在调取接口时不传 sub_mch_id，获取服务商下全量特约商户（包括小微商户和非小微商户）的对账单。

## 接口地址

``` bash
http://api.weixin.qq.com/_/pay/downloadbill
```

## 入参数据

``` json
{
  "bill_date":"20220321",
  "bill_type":"ALL",
  "sub_mch_id":"176531292"
}
```

## 出参数据

有数据时，返回如下：

``` json
{ 
  "errcode":0, 
  "errmsg":"ok", 
  "respdata": 交易时间,公众账号ID,商户号,特约商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,应结订单金额,代金券金额,微信退款单号,商户退款单号,退款金额,充值券退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率,订单金额,申请退款金额,费率备注
              `2022-03-21 13:51:31,`wxfdc955f7104ad557,`180023671,`176531292,`,`420000612032130748613220688,`2021WERUN1647840687637,`oZWaCKXip5njeEiloC4oeOV1TTsk,`JSAPI,`SUCCESS,`OTHERS,`CNY,`0.01,`0.00,`0,`0,`0.00,`0.00,`,`,`微信云托管支付测试,`,`0.00000,`0.90%,`0.01,`0.00,`
              总交易单数,应结订单总金额,退款总金额,充值券退款总金额,手续费总金额,订单总金额,申请退款总金额
              `12,`0.06,`0.06,`0.00,`0.00000,`0.06,`0.06
 }
```

无数据时，或其他错误时，格式如下：

``` json
{
  "errcode":0,
  "errmsg":"ok",
  "respdata":{
    "return_code":"FAIL",
    "return_msg":"No Bill Exist",
    "error_code":"20002"
  }
}
```

## 参数说明

| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|--------|---|------|---|----|---|
| 子商户号 | sub_mch_id | 否 | String(32) | 1900000109 | 微信支付分配的子商户号，如需下载指定的子商户号对账单，则此参数必传。 |
| 随机字符串 | nonce_str| 是 | String(32) | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | 随机字符串，不长于32位。推荐随机数生成算法 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名，详见签名生成算法 |
| 对账单日期 | bill_date| 是 | String(8)| 20140603 | 下载对账单的日期，格式：20140603 |
| 账单类型 | bill_type| 否 | String(8)| ALL| ALL，返回当日所有订单信息，默认值
SUCCESS，返回当日成功支付的订单
REFUND，返回当日退款订单
 |
| 压缩账单 | tar_type | 否 | String | GZIP | 非必传参数，固定值：GZIP，返回格式为.gzip的压缩包账单。不传则默认为数据流形式。|

## 返回值说明

失败时，返回以下字段

| 字段名 | 变量名| 必填 | 类型| 示例值 | 描述|
|---|---|------|---|---|---------|
| 返回状态码 | return_code | 是 | String(16)| FAIL | FAIL|
| 错误码描述 | return_msg| 否 | String(128) | 签名失败 | 返回信息，如非空，为错误原因，如：签名失败 等。 |
| 错误码 | error_code| 否 | String(16)| 20002| 失败错误码，详见错误码列表|

成功时，数据以文本表格的方式返回，第一行为表头，后面各行为对应的字段内容，字段内容跟查询订单或退款结果一致，具体字段说明可查阅相应接口。

第一行为表头，根据请求下载的对账单类型不同而不同(由 bill_type 决定)，目前有：

- **当日所有订单**
交易时间，服务商的 APPID，商户号，子商户号，设备号，微信订单号，商户订单号，用户标识，交易类型，交易状态，付款银行，货币种类，总金额，代金券或立减优惠金额，微信退款单号，商户退款单号，退款金额，代金券或立减优惠退款金额，退款类型，退款状态，商品名称，商户数据包，手续费，费率

- **当日成功支付的订单**
交易时间，服务商的 APPID，商户号，子商户号，设备号，微信订单号，商户订单号，用户标识，交易类型，交易状态，付款银行，货币种类，总金额，代金券或立减优惠金额，商品名称，商户数据包，手续费，费率

- **当日退款的订单**
交易时间，服务商的 APPID，商户号，子商户号，设备号，微信订单号，商户订单号，用户标识，交易类型，交易状态，付款银行，货币种类，总金额，代金券或立减优惠金额，退款申请时间，退款成功时间，微信退款单号，商户退款单号，退款金额，代金券或立减优惠退款金额，退款类型，退款状态，商品名称，商户数据包，手续费，费率

从第二行起，为数据记录，各参数以逗号分隔，参数前增加 ` 符号，为标准键盘 1 左边键的字符，字段顺序与表头一致。

倒数第二行为订单统计标题，最后一行为统计数据

总交易单数，总交易额，总退款金额，总代金券或立减优惠退款金额，手续费总金额

举例如下：

```bash
交易时间，服务商的APPID，商户号，子商户号，设备号，微信订单号，商户订单号，用户标识，交易类型，交易状态，付款银行，货币种类，总金额，代金券或立减优惠金额，微信退款单号，商户退款单号，退款金额，代金券或立减优惠退款金额，退款类型，退款状态，商品名称，商户数据包，手续费，费率
`2014-11-10 16：33：45,`wx2421b1c4370ec43b,`10000100,`0,`1000,`1001690740201411100005734289,`1415640626,`085e9858e3ba5186aafcbaed1,`MICROPAY,`SUCCESS,`OTHERS,`CNY,`0.01,`0.0,`0,`0,`0,`0,`,`,`被扫支付测试,`订单额外描述,`0,`0.60%
`2014-11-10 16：46：14,`wx2421b1c4370ec43b,`10000100,`0,`1000,`1002780740201411100005729794,`1415635270,`085e9858e90ca40c0b5aee463,`MICROPAY,`SUCCESS,`OTHERS,`CNY,`0.01,`0.0,`0,`0,`0,`0,`,`,`被扫支付测试,`订单额外描述,`0,`0.60%
总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额
`2,`0.02,`0.0,`0.0,`0
```

## 结算对账单

### 一、普通结算对账单

| 字段名称 | 示例值 | 字段说明 |
|------|---|--------|
| 交易时间 | 2017-12-14 15:49:06| 指该笔交易的支付成功时间或发起退款成功时间（注意：不是退款成功时间），格式为YYYY-MM-DD HH:MM:SS，如2015-01-01 10:00:00 |
| 公众账号ID | wxab8acb865bb11234 | 发起该笔交易时使用的appid，appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景|
| 商户号 | 1234567890 | 发起该笔交易的微信支付商户号，8~10位数字 |
| 子商户号 | 0| 如果是普通受理模式下的交易，展示特约商户的商户号，8~10位数字
如果是直连模式交易，则展示成数字0|
| 设备号 | 8888 | 该笔交易下单时在device_info字段中传入的信息，没填写则留空|
| 微信订单号 | 4200000008201712143733500001 | 微信支付为该笔订单（或该笔退款对应的订单）分配的订单号 |
| 商户订单号 | test1| 商户传入的该笔订单（或该笔退款对应的订单）的商户订单号，对应下单接口里的out_trade_no字段 |
| 用户标识 | testxt08c-XB5-QD208X1Aid0Cbs | 微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid)|
| 交易类型 | NATIVE | 该笔订单（或该笔退款单对应的订单）的交易类型，使用英文缩写展示，取值和含义： 值：
JSAPI-JSAPI支付（或小程序支付）
NATIVE-Native支付
APP-app支付
MWEB-H5支付
MICROPAY-付款码支付
PAP-委托代扣 |
| 交易状态 | SUCCESS| SUCCESS—支付成功，说明该行数据为一笔支付成功的订单
REFUND—转入退款，说明该行数据为一笔发起退款成功的退款单
REVOKED—已撤销，说明该行数据为一笔成功撤销的撤销单|
| 付款银行 | OTHERS | 银行类型，采用字符串类型的银行标识，如CMC_CREDIT，完整说明见https://pay.weixin.qq.com/doc/v2/merchant/4011941162#8%E3%80%81%E9%93%B6%E8%A1%8C%E7%B1%BB%E5%9E%8B |
| 货币种类 | CNY| 货币类型，符合ISO 4217标准的三位字母代码，如CNY|
| 总金额 | 0.01 | 该笔订单的应结算金额（=订单金额-用户使用的免充值券金额），如果该行数据为退款或撤销则展示0.00，单位元，保留到小数点后2位|
| 代金券或立减优惠金额 | 0.00 | 该笔订单中使用的微信支付代金券金额（包括充值券和免充值券），如果未使用代金券、或该行数据为退款或撤销则展示0.00，单位元，保留到小数点后2位|
| 微信退款单号 | 0| 微信支付为该笔退款分配的退款单号，如果该行数据为订单则展示0|
| 商户退款单号 | 0| 商户发起退款时填入的商户退款单号，如果该行数据为订单则展示0|
| 退款金额 | 0.00 | 该笔退款或撤销单的应结算金额（申请退款金额-免充值券退款金额），如果该行数据为订单则展示为0.00，非负数、单位元，保留到小数点后2位 |
| 代金券或立减优惠退款金额 | 0.00 | 退款金额中包含的充值券退款金额，如果该行数据为订单或没有充值券退款则展示为0.00，非负数、单位元，保留到小数点后2位|
| 退款类型 || ORIGINAL—原路退款
BALANCE—转退到用户的微信支付零钱
如果该行数据为订单，则留空|
| 退款状态 || 生成账单文件时该笔退款的状态、后续不会更新，如果该行数据为订单，则留空
SUCCESS—退款成功
FAIL—退款失败
PROCESSING—退款处理中 |
| 商品名称 | 中文[body] | 商户传入的该笔订单（或该笔退款对应的订单）的商品名称，对应下单接口里的body字段 |
| 商户数据包 | 测试中文[attach] | 商户传入的该笔订单（或该笔退款对应的订单）的商户数据包，对应下单接口里的attach字段，不传时留空 |
| 手续费 | 0.00000| 该笔订单/退款对应的手续费金额，订单对应正数、退款对应负数，单位元，保留小数点后2位 |
| 费率 | 0.00%| 该笔交易计费所使用的费率，百分数，如0.60%|

### 二、开通免充值券后的结算对账单

| 字段名称 | 示例值 | 字段说明 |
|------|----|--------|
| 交易时间 | 2017-12-14 15:49:06| 指该笔交易的支付成功时间或发起退款成功时间（注意：不是退款成功时间），格式为YYYY-MM-DD HH:MM:SS，如2015-01-01 10:00:00 |
| 公众账号ID | wxab8acb865bb11234 | 发起该笔交易时使用的appid，appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景|
| 商户号 | 1234567890 | 发起该笔交易的微信支付商户号，8~10位数字 |
| 特约商户号 | 0| 如果是普通受理模式下的交易，展示特约商户的商户号，8~10位数字
如果是直连模式交易，则展示成数字0|
| 设备号 | 8888 | 该笔交易下单时在device_info字段中传入的信息，没填写则留空|
| 微信订单号 | 4200000008201712143733500001 | 微信支付为该笔订单（或该笔退款对应的订单）分配的订单号 |
| 商户订单号 | test1| 商户传入的该笔订单（或该笔退款对应的订单）的商户订单号，对应下单接口里的out_trade_no字段 |
| 用户标识 | testxt08c-XB5-QD208X1Aid0Cbs | 微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid)|
| 交易类型 | NATIVE | 该笔订单（或该笔退款单对应的订单）的交易类型，使用英文缩写展示，取值和含义： 值：
JSAPI-JSAPI支付（或小程序支付）
NATIVE-Native支付
APP-app支付
MWEB-H5支付
MICROPAY-付款码支付
PAP-委托代扣 |
| 交易状态 | SUCCESS| SUCCESS—支付成功，说明该行数据为一笔支付成功的订单
REFUND—转入退款，说明该行数据为一笔发起退款成功的退款单
REVOKED—已撤销，说明该行数据为一笔成功撤销的撤销单|
| 付款银行 | OTHERS | 银行类型，采用字符串类型的银行标识，如CMC_CREDIT，完整说明见https://pay.weixin.qq.com/doc/v2/merchant/4011941162#8%E3%80%81%E9%93%B6%E8%A1%8C%E7%B1%BB%E5%9E%8B |
| 货币种类 | CNY| 货币类型，符合ISO 4217标准的三位字母代码，如CNY|
| 应结订单金额 | 0.01 | 该笔订单的应结算金额（=订单金额-用户使用的免充值券金额），如果该行数据为退款或撤销则展示0.00，单位元，保留到小数点后2位|
| 代金券金额 | 0.00 | 该笔订单中使用的微信支付代金券金额（包括充值券和免充值券），如果未使用代金券、或该行数据为退款或撤销则展示0.00，单位元，保留到小数点后2位|
| 微信退款单号 | 0| 微信支付为该笔退款分配的退款单号，如果该行数据为订单则展示0|
| 商户退款单号 | 0| 商户发起退款时填入的商户退款单号，如果该行数据为订单则展示0|
| 退款金额 | 0.00 | 该笔退款或撤销单的应结算金额（申请退款金额-免充值券退款金额），如果该行数据为订单则展示为0.00，非负数、单位元，保留到小数点后2位 |
| 充值券退款金额 | 0.00 | 退款金额中包含的充值券退款金额，如果该行数据为订单或没有充值券退款则展示为0.00，非负数、单位元，保留到小数点后2位|
| 退款类型 || ORIGINAL—原路退款
BALANCE—转退到用户的微信支付零钱
如果该行数据为订单，则留空|
| 退款状态 || 生成账单文件时该笔退款的状态、后续不会更新，如果该行数据为订单，则留空
SUCCESS—退款成功
FAIL—退款失败
PROCESSING—退款处理中 |
| 商品名称 | 中文[body] | 商户传入的该笔订单（或该笔退款对应的订单）的商品名称，对应下单接口里的body字段 |
| 商户数据包 | 测试中文[attach] | 商户传入的该笔订单（或该笔退款对应的订单）的商户数据包，对应下单接口里的attach字段，不传时留空 |
| 手续费 | 0.00000| 该笔订单/退款对应的手续费金额，订单对应正数、退款对应负数，单位元，保留小数点后2位 |
| 费率 | 0.00%| 该笔交易计费所使用的费率，百分数，如0.60%|
| 订单金额 | 0.01 | 该笔订单的金额，包括用户支付金额、充值券金额、免充值券金额，如果该行数据为退款或撤销则填0.00，单位元，保留到小数点后2位|
| 申请退款金额 | 0.00 | 商户发起退款的金额，包括退给用户的金额、充值券退款金额、免充值券退款金额，如果该行数据订单则填0.00，单位元，保留到小数点后2位|
| 费率备注 || 如果有特殊费率规则时则加以说明，默认留空 |

## 错误码

| 错误码 | 名称| 描述| 原因 | 解决方案 |
|--------|---------|---|----|---|
| 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权限已经关闭，请联系微信支付解决|
| 20100| system error| 下载失败| 系统超时 | 请尝试再次查询。 |