Login expired. Please log in again.




Submitted successfully



Network exception, please try again later


Download Reconciliation File API

Latest update time:2019.11.20 Release notes

This API is used to help the Merchants download their transaction record history including missing orders, and can be used to find unmatched data between merchants and WeChat caused by system error. By downloading transaction history and doing reconciliation, the Merchant can correct the status of their orders in a timely fashion.


1. Transactions that are not ordered successfully are excluded in this reconciliation form, while orders that are revoked after successful payment will still be included. Included orders shall be consistent with the original payment bill number, that is, the value of bill_type will be set to REVOKED;

2. Each day's reconciliation file download is created at 9:00 AM the following day. Therefore, merchants can download it after 10:00 AM (UTC+08);

3. The currency unit used in the reconciliation form is bid currency unit. (Like Chinese yuan, US dollar).

4. This API can only download the transactions within 3 months.

API intro

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

Request Method: POST

Certificate Requirements: No certificate is required.

Applicable Object: Common modeInstitutional mode

Request Parameters

Name ID Type Required Description
Official Account ID appid String(32) Yes Specifies Official Account ID assigned by WeChat
Example: wx8888888888888888
Merchant ID mch_id String(32) Yes Specifies merchant ID assigned by WeChat Payment
Example: 1900000109
Sub Official Account ID sub_appid String(32) No Specifies an sub Official Account ID assigned by WeChat
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: wx8888888888888888
Sub  Merchant ID sub_mch_id String(32) No Specifies sub merchant ID assigned by WeChat Payment. Required if needs to download reconciliation file of a specified sub merchant.
Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay
Note: Only for Institutional mode
Example: 1900000109
Device ID device_info String(32) No Specifies the terminal device ID assigned by WeChat Payment. This field specifies the transactions related to this device.
Example: 013467007045764
Random String nonce_str String(32) Yes 32 characters or fewer. For more information, see Random String Algorithm.
Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS
Signature sign String(64) Yes Specifies a signature. For more information, see Signature Algorithm.
Example: C380BEC2BFD727A4B6845133519F3AD6
Sign type sign_type String(32) NO This field is only required when sign_type is HMAC-SHA256. Default is MD5.
Example: HMAC-SHA256
Reconciliation Start Date bill_date String(8) Yes Specifies the date of the transactions to be downloaded in the format of yyyymmdd, such as 20140603 for June 3, 2014.
Example: 20140603
Bill Type bill_type String(8) Yes ALL: Return all order data from the specified date. bill_type is set to ALL by default.
SUCCESS: Return successfully paid orders only
REFUND: Return refunded orders only
Example: ALL
Compress Type tar_type String(8) No Fixed value: GZIP. It will return a .gzip package if this parameter is set, unless it will return the data flow.
Example: GZIP



Return Data

If the request has failed, the following fields will be returned.

Name ID Type Required Description
Return Status Code return_code String(16) Yes FAIL
Return Data return_msg String(128) No If not empty, this is the error description
Signature failure
Parameter format checking error
The order date is not created
Example: Signature failure

When the request has succeeds, the returned data will include a header row containing the data fields of the subsequent rows.

The first row will be the header row, with the value based upon the Bill Type (as specified by bill_type) requested by the Merchant and containing the included data fields of the subsequent row.

Transaction records begin from the second row, and transaction fields are comma-separated values and begin with the “`” character (to the right of the “1” key on a standard keyboard) and in the same order as the fields listed in the header row of the returned data.

The second to last row will contain descriptive headers of the transaction history statistics and the last row will contain the statistical values of the returned transactions:

Total transactions, Total order amount, Total refunded amount, Total mobile coupon amount, Total mobile coupon refunds

An example of returned data follows:

Transaction time, Official account ID(appid), Vendor ID(mch_id), Sub vendor ID(sub_mch_id), Device ID(Device_info), Wechat order number(transaction_id), Vendor order number(out_transaction_id), User tag(openid), Transaction type(trade_type), Transaction status(trade_state), Payment bank(bank_type), Currency type(fee_type), Total amount(total_fee), Coupon amount, Wechat refund number(refund_id), Merchant refund number(out_refund_no), Refund amount(refund_fee), Coupon refund amount, Refund type, Refund status(refund_status_$n), Product name, Merchant’s data package(attach), Fee, Rate, Payment Currency type(Cash_fee_type), Cash payment amount(Cash_fee), Settlement currency type, Settlement currency amount, Exchange rate, Refund exchange rate, Payer’s Refund amount, Payer’s Refund currency type, Refund currency type, Refund settlement currency type, Refund settlement amount

`0.00,`0,`0,`0,`0,`,`,`promotion ,`,`1.19000,`0.60%,`CNY,`168.01,`HKD,`198.00,`84853800,`0,`0,`,`,`,`0

At the end of each transaction history form, there is the statistic information, please refer to the following fields for detailed information:

Total transaction count, Total transaction amount, Total refund amount, Total coupon refund amount, Total commission amount

An example is as following:

Total transaction count Total transaction amount Total refund amount Total coupon refund amount Total commission amount
`110 `6096.73 `0.00 `0.00 `152.45000

Error Codes

Error code Name Description Reason Solution
20003 SYSTEMERROR API return error System timed out Try to query again
20001 invalid bill_type Parameter error Requested parameters are not correct Parameter error. Check parameters and try again.
sign error Signature error Signature error Please check the signature
nonce_str too long nonce_str parameter error The length of nonce_str is out of limit Please input the parameters with the valid length
invalid tar_type, Only GZIP supported tar_type parameter error tar_type value is wrong or format is wrong Please input the parameters following the rules
invalid bill_date bill_date parameter error bill_date parameter format is wrong Please input the parameters following the rules
require POST method Request method error The request method is incorrect Please check whether requesting with POST method
empty post data POST data error There is no POST data found Please check whether the POST data is empty
data format error Data format error Data is not transferred with xml format Please transfer data with xml format
missing parameter The required parameters are missing The required parameters are missing Please transfer all the required parameters
invalid appid invalid appid The appid parameter is invalid Please check the appid and transfer the righ one
invalid parameter Parameter error There is invalid parameter transferred Please transfer the right parameters
20002 Bill Creating The report is not created yet There is no successful transactions for the specified date or the report is generating Please check whether there are successful transactions in the specified data. If there is, please, please call the API after 10 a.m. GTM+8.
NO Bill Exist There is no bill generated The current merchant ID has no transaction for the specific time range Please check whether there are transactions on the specific dates
20007 The API authorty of the merchant account has been dosed No authority to use the API Merchant’s authority is closed Please contact the business director for help
20100 system error Download failure System timeout Please retry later

Release notes

1. Download Reconciliation File API released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2019 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

Wechat Pay Global