Download Reconciliation File

Update Time：2025.02.20

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.

Tips：

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;
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);
The currency unit used in the reconciliation form is bid currency unit. (Like Chinese yuan, US dollar).
This API can only download the transactions within 3 months.

API intro

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

Request Method: POST

Certificate Requirements: No certificate is required.

Applicable Object: Common mode Institutional 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

Example：

1<xml>
2   <appid>wx2421b1c4370ec43b</appid>
3   <bill_date>20141110</bill_date>
4   <bill_type>ALL</bill_type>
5   <mch_id>10000100</mch_id>
6   <nonce_str>21df7dc9cd8616b56919f20d9f679233</nonce_str>
7   <sign>332F17B766FC787203EBE9D6E40457A1</sign>
8</xml>

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 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
Transaction time	Format: YYYY-MM-DD HH:MM:SS	`2024-03-09 19:15:48	`2024-03-09 19:46:27
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
Total amount(total_fee)	The value is 0.00 if the transaction is a refund.	`499.00	`0.00
Coupon amount	Amount of coupons associated with the transaction.	`0.00	`0.00
Coupon amount	The value is 0.00 if the transaction is a refund.	`0.00	`0.00
Wechat refund number(refund_id)	Wechat Pay's unique reference associated with the refund.	`0	`50201309022024030935709090246
Wechat refund number(refund_id)	The value is 0 if the transaction is a payment.	`0	`50201309022024030935709090246
Vendor refund number(out_refund_no)	Your reference for the refund.	`0	`20240309458898381658624512
Vendor refund number(out_refund_no)	The value is 0 if the transaction is a payment.	`0	`20240309458898381658624512
Refund amount(refund_fee)	Gross refund amount	`0.00	`499.00
Refund amount(refund_fee)	The value is 0.00 if the transaction is a payment.	`0.00	`499.00
Coupon refund amount	Amount of coupons associated with the transaction.	`0.00	`0.00
Coupon refund amount	The value is 0.00 if the transaction is a payment.	`0.00	`0.00
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
Settlement currency amount	The value is 0.00 if the transaction is a refund.	`538.95	`0.00
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
Refund exchange rate	The value is 0.00 if the transaction is a payment.	`0	`92585931
Payer’s Refund amount	The amount refund to the user.	`0	`499.00
Payer’s Refund amount	The value is 0.00 if the transaction is a payment.	`0	`499.00
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
Refund settlement amount	The value is 0.00 if the transaction is a payment.	`0.00	`538.95
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 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.
20002	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