Latest update time：2024.03.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.
Request Url: https://api.mch.weixin.qq.com/pay/downloadbill
Request Method: POST
Certificate Requirements: No certificate is required.
Applicable Object: Common modeInstitutional mode
| 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 |
<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>
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
Example：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.
| Field Name | Field Description | Payment Example | Refund Example |
|---|---|---|---|
| Transaction time | Time stamp indicating when the transaction was processed by WechatPay. | `2024-03-09 19:15:48 | `2024-03-09 19:46:27 |
| Format: YYYY-MM-DD HH:MM:SS | |||
| Official account ID(appid) | Wechat Pay's unique reference associated with the Wechat offcial account or Wechat micro app. | `wx87b0b4160031234 | `wx87b0b4160031234 |
| Vendor ID(mch_id) | Wechat Pay's unique MerchantId attributed to each merchant | `123450000 | `123450000 |
| Sub vendor ID(sub_mch_id) | Wechat Pay's unique sub merchant id attributed to each sub-merchant | `600000001 | `600000001 |
| Device ID(Device_info) | ID of the terminal where the transaction occurred ( as sent in the original payment request, can have blanks) | `013467007045764 | `013467007045764 |
| Wechat order number(transaction_id) | Wechat Pay's unique reference associated with the transaction. | `4200002193202403093640737027 | `4200002193202403093640737027 |
| Vendor order number(out_transaction_id) | Your reference for the transaction. This is the out_trade_no from the original payment request. | `20240309458890656874661888 | `20240309458890656874661888 |
| User tag(openid) | The unique identifier of the payer in the payment transaction. | `oc-J25YZ8cfVl0pBgwQfjIjkgAB1 | `oc-J25YZ8cfVl0pBgwQfjIjkgAB1 |
| Transaction type(trade_type) | The type of transaction. Possible values are: | `JSAPI | `JSAPI |
| MICROPAY | |||
| JSAPI | |||
| NATIVE | |||
| APP | |||
| FACE | |||
| Transaction status(trade_state) | The type of transaction. Possible values are: | `SUCCESS | `REFUND |
| SUCCESS，representing a payment transaction | |||
| REFUND, representing a refund transaction | |||
| Payment bank(bank_type) | Users' payment source. The possible values are: | `CCB_DEBIT | `CCB_DEBIT |
| XXX_CREDIT, representing a credit card from XXX bank | |||
| XXX_DEBIT, representing a debit card from XXX bank | |||
| WPHK, representing HK wallet balance | |||
| OTHERS, representing CN wallet balance, mutual fund balance, etc | |||
| Currency type(fee_type) | Three character ISO code for the currency which was used for processing the payment (quotation currency) | `CNY | `CNY |
| Total amount(total_fee) | Gross payment amount in quotation currency | `499.00 | `0.00 |
| The value is 0.00 if the transaction is a refund. | |||
| Coupon amount | Amount of coupons associated with the transaction. | `0.00 | `0.00 |
| The value is 0.00 if the transaction is a refund. | |||
| Wechat refund number(refund_id) | Wechat Pay's unique reference associated with the refund. | `0 | `50201309022024030935709090246 |
| The value is 0 if the transaction is a payment. | |||
| Vendor refund number(out_refund_no) | Your reference for the refund. | `0 | `20240309458898381658624512 |
| The value is 0 if the transaction is a payment. | |||
| Refund amount(refund_fee) | Gross refund amount | `0.00 | `499.00 |
| The value is 0.00 if the transaction is a payment. | |||
| Coupon refund amount | Amount of coupons associated with the transaction. | `0.00 | `0.00 |
| The value is 0.00 if the transaction is a payment. | |||
| Refund type | ORIGINAL--refund to the original payment method BALANCE-refund to Wechat Pay balance null if the transaction is a payment |
` | `ORIGINAL |
| Refund status(refund_status) | Refund status when the transaction report is generated, which won't update. Possible values are: | ` | `SUCCESS |
| SUCCESS，退款成功 | |||
| PROCESSING，退款处理中 | |||
| Product name | This is the "body" from the original payment request. | `80695507873 | `80695507873 |
| Vendor's data package(attach) | This is the "attach" from the original payment request. It is not unique and can have blanks. | ` | ` |
| Fee | Fee charged/refunded by the Wechat Pay for processing the transaction(in settlement currency). | `2.69000 | `-2.69000 |
| Rate | Fee rate | `0.50% | `0.50% |
| Payment Currency type(Cash_fee_type) | Three character ISO code for the currency which was used for processing the payment (payment currency) | `CNY | `CNY |
| Cash payment amount(Cash_fee) | The amount paid by the user. | `499.00 | `0.00 |
| Settlement currency type | Three character ISO code for the currency which was used for processing the payment (settlement currency) | `HKD | `HKD |
| Settlement currency amount | Transaction amount in settlement currency | `538.95 | `0.00 |
| The value is 0.00 if the transaction is a refund. | |||
| Exchange rate | Exchange rate used for converting the Cash payment amount into the Settlement currency amount. | `92585931 | `0 |
| Refund exchange rate | Exchange rate used for converting the Payer’s Refund amount into the Refund settlement amount. | `0 | `92585931 |
| The value is 0.00 if the transaction is a payment. | |||
| Payer’s Refund amount | The amount refund to the user. | `0 | `499.00 |
| The value is 0.00 if the transaction is a payment. | |||
| Payer’s Refund currency type | Three character ISO code for the currency which was used for processing the refund (payment currency) | ` | `CNY |
| Refund currency type | Three character ISO code for the currency which was used for processing the refund (payment currency) | ` | `CNY |
| Refund settlement currency type | Three character ISO code for the currency which was used for processing the refund (settlement currency) | ` | `HKD |
| Refund settlement amount | Transaction amount in settlement currency | `0.00 | `538.95 |
| The value is 0.00 if the transaction is a payment. | |||
| Fund type (available in new version） | Whether the payment is splitted into difference account: | `NonSplittingOrder | `NonSplittingOrder |
| SplittingOrder | |||
| NonSplittingOrder | |||
| Fee RMB (available in new version） | Fee charged/refunded by the Wechat Pay for processing the transaction (in CNY). | `2.50000 | `2.50000 |
| Refund account (available in new version） | The funding source of the refund, possible values are: | ` | `UnsettledFund |
| UnsettledFund，the fund not yet settled | |||
| RechargeFund, the fund manually added by the merchant |
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 last 2 lines of the reconciliation file shows a summary of all the transactions, with detailed fields as follows:
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 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 |
| 20008 | Frequency Limited | Request frequency exceeds limit | Current IP or merchant account requests are too frequent，exceeded frequency limit | Please slow down the request speed and retry later |
| 20100 | system error | Download failure | System timeout | Please retry later |
| 100 | Network_Traffic_Limit | Network traffic restrictions | The current system request is busy | Please try querying again |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证