Downloading Reconciliation

Update Time：2025.01.07

Merchants can download the transaction history via this API. For example, the data from the merchant side and WeChat may be inconsistent due to record missing or system error, and the payment status can be corrected after the statement check.

Tips：

Bill integrity check: After the bill is completely downloaded and the SHA1 signature is generated, compare the bill with the Wechatpay-Statement-Sha1 value of HTTP header returned by WeChat.
The Downloading Reconciliation API can only download bills within 180 days.

1. API intro

Applicable object: Common mode Institutional mode

Request URL: https://apihk.mch.weixin.qq.com/v3/global/statements

Request method: GET

Path parameter is a path parameter.

Query parameter needs to be passed in the request URL.

Body parameter needs to be passed in the request JSON.

2. Request Parameters

Name	Variable Name	Type	Required	Description
Bill date	date	string[1，8]	Yes	Query Bill date in the format of 20180103 The Downloading Reconciliation API can only download bills within 180 days. Example: 20180130
Institution's Merchant ID	sp_mchid	string[1,32]	Yes	Query Institution's Merchant ID assigned by WeChat Pay Note: Only for Institutional mode Example: 1900000109
Sub-merchant ID	sub_mchid	string[1,32]	No	Query Sub-merchant I assigned by WeChat Pay. If the sub_mchid is passed in, only the reconciliation for the sub-merchant transactions will be returned. If the sub_mchid is not passed in, the reconciliation for all sub-merchant transactions of the institution will be returned. Note: Only for Institutional mode Example: 1900000109
Merchant ID	mchid	string[1,32]	Yes	Query Merchant ID assigned by WeChat Pay Note: Only for Common mode Example: 1900000109

Request Example

Common Mode

1https://apihk.mch.weixin.qq.com/v3/global/statements?date=20180130&mchid=1900000109

Institution Mode

1https://apihk.mch.weixin.qq.com/v3/global/statements?date=20180130&sp_mchid=1900000109
2https://apihk.mch.weixin.qq.com/v3/global/statements?date=20180130&sp_mchid=1900000109&sub_mchid=1900000102

3. Response Parameters

Response for successful request:

When the request is successful, the data is returned in the form of a text table. The first row is the header and the following rows list the corresponding field content. The field content is consistent with the query order or the refund result. For specific field description, you can refer to the corresponding APIs.

The first row is the header. Currently it includes transaction time, Official Account ID, Vendor ID, Sub vendor ID, Device No., WeChat order No., Vendor order No., User identifier, transaction type, transaction status, payment bank, top-up voucher currency, top-up voucher amount, voucher currency, voucher amount, WeChat refund No., merchant refund No., refund type, refund status, commodity name, merchant data package, service fee, rate, priced currency, order amount (priced currency), user payment currency, user payment amount, settlement currency, order settlement amount payable, payment exchange rate, refund exchange rate, application refund amount, user refund currency, user refund amount, refund settlement currency, refund settlement amount payable, top-up voucher refund amount, and voucher refund amount.
Data record is provided from the second row. Parameters are separated by comma, and the symbol ` is added before the parameter, which is to the left of 1 of a standard keyboard. The field order is consistent with the header.

Field Name	Type	Field Description	Payment Example	Refund Example
Transaction Time	varchar(255)	Time stamp indicating when the transaction was processed by WechatPay. Format: YYYY-MM-DD HH:MM:SS	`2024-03-11 10:00:00	`2024-03-11 10:00:00
Official Account ID(appid)	varchar(255)	Wechat Pay's unique reference associated with the Wechat offcial account or Wechat micro app.	`wx87b0b4160031234	`wx87b0b4160031234
Vendor ID(mchid)	varchar(255)	Wechat Pay's unique MerchantId attributed to each merchant	`123450000	`123450000
Sub vendor ID(sub_mchid)	varchar(255)	Wechat Pay's unique sub merchant id attributed to each sub-merchant	`600000001	`600000001
Device ID(device_id)	varchar(255)	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)	varchar(255)	Wechat Pay's unique reference associated with the transaction.	`4200002158202403119854123456	`4200002158202403119854123456
Vendor Order Number(out_trade_no)	varchar(255)	Your reference for the transaction. This is the out_trade_no from the original payment request.	`20240311105346P3791	`20240311105346P3791
User Tag(openid)	varchar(255)	The unique identifier of the payer in the payment transaction.	`oZPPassSdACFwnRNEVQVAkvj_5NU	`oZPPassSdACFwnRNEVQVAkvj_5NU
Transaction Type(trade_type)	varchar(50)	The type of transaction. Possible values are: MICROPAY JSAPI NATIVE APP FACE	`NATIVE	`NATIVE
Transaction Status(trade_state)	varchar(50)	The type of transaction. Possible values are: SUCCESS，representing a payment transaction REFUND, representing a refund transaction	`SUCCESS	`REFUND
Payment Bank(bank_type)	varchar(50)	Users' payment source. The possible values are: 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	`CMB_CREDIT	`CMB_CREDIT
Top-up Voucher Currency Type	varchar(50)	Coupon Currency（quotation currency）	`	`
Top-up Voucher Amount	varchar(255) Floating-point string, retain 2 decimal places	Coupon amount （in quotation currency)	`0.00	`0.00
Coupon Currency Type	varchar(50)	NOT APPLICABLE	`	`
Coupon Amount	varchar(255) Floating-point string, retain 2 decimal places	NOT APPLICABLE	`0.00	`0.00
Wechat Refund Number(refund_id)	varchar(255)	Wechat Pay's unique reference associated with the refund. The value is 0 if the transaction is a payment.	`	`50202407752024031135708554321
Vendor Refund Number(out_refund_no)	varchar(255)	Your reference for the refund. The value is 0 if the transaction is a payment.	`	`20240311459568556791724321
Refund Channel	varchar(50)	ORIGINAL--refund to the original payment method BALANCE-refund to Wechat Pay balance null if the transaction is a payment	`	`ORIGINAL
Refund Status	varchar(50)	Refund status when the transaction report is generated, which won't update. Possible values are: SUCCESS, refund is successful Processing, refund is still in processing, the fund has already been deducted from the account of institution, but not reach to the consumer yet.	`	`SUCCESS
Product Name(description)	varchar(255)	This is the "body" from the original payment request.	`E8D253EF9036	`E8D253EF9036
Merchant's Data Package(attach)	varchar(255)	This is the "attach" from the original payment request. It is not unique and can have blanks.	`3EF9E1D25036	`3EF9E1D25036
Fee	varchar(255) Floating-point string, retain 5 decimal places	Fee charged/refunded by the Wechat Pay for processing the transaction(in settlement currency). Fee amount calculation rule: multiply the single transaction amount by the fee rate, then round the result to the smallest unit supported by the currency using standard rounding (round half up). For example, If the transaction amount is 100 JPY and the fee rate is 5‰ (0.5%), the calculated fee is 0.5 JPY; since the smallest unit for JPY is 1 yen, rounding yields a fee of 1 JPY. If the transaction amount is 1 USD and the fee rate is 5‰ (0.5%), the calculated fee is 0.005 USD; since the smallest unit for USD is 1 cent, rounding yields a fee of 0.01 USD.	`0.33000	`-0.08000
Rate	varchar(10)	Fee rate	`0.50%	`0.50%
Transaction Currency Type	varchar(50)	Three character ISO code for the currency which was used for processing the payment (quotation currency)	`HKD	`HKD
Transaction Amount(total)	varchar(255) Floating-point string, retain 2 decimal places	Gross payment amount in quotation currency The value is 0.00 if the transaction is a refund.	`65.66	`0.00
Payer Currency Type(payer_currency)	varchar(50)	Three character ISO code for the currency which was used for processing the payment (payment currency)	`CNY	`CNY
Payer Payment Amount(payer_total)	varchar(255) Floating-point string, retain 2 decimal places	The amount paid by the user.	`60.45	`0.00
Settlement Currency Type	varchar(50)	Three character ISO code for the currency which was used for processing the payment (settlement currency)	`HKD	`HKD
Settlement Currency Amount	varchar(255) Floating-point string, retain 2 decimal places	Transaction amount in settlement currency The value is 0.00 if the transaction is a refund.	`65.66	`0.00
Transaction Exchange Rate	varchar(255) Integer string	Exchange rate used for converting the Cash payment amount into the Settlement currency amount.	`92067840	`92067840
Refund Exchange Rate	varchar(255) Integer string	Exchange rate used for converting the Payer’s Refund amount into the Refund settlement amount. The value is 0.00 if the transaction is a payment.	`0	`0
Refund Amount	varchar(255) Floating-point string, retain 2 decimal places	Refund amount (quotation currency)	`0	`16.00
Payer Refund Currency Type	varchar(50)	Three character ISO code for the currency which was used for processing the refund (payment currency)	`	`CNY
Payer Refund Amount	varchar(255) Floating-point string, retain 2 decimal places	The amount refund to the user. The value is 0.00 if the transaction is a payment.	`0	`14.73
Refund Settlement Currency Type	varchar(50)	Three character ISO code for the currency which was used for processing the refund (settlement currency)	`	`HKD
Refund Amount for merchant in settlement currency	varchar(255) Floating-point string, retain 2 decimal places	Transaction amount in settlement currency The value is 0.00 if the transaction is a payment.	`0	`16.00
Refund Amount of Top-up Voucher	varchar(255) Floating-point string, retain 2 decimal places	The amount refund to the coupon account.	`0	`0.00
Refund Amount of Coupon	varchar(255) Floating-point string, retain 2 decimal places	NOT APPLICABLE	`0	`0.00

If the merchant expands the funds-distribution and recharge refund fields, the following three fields will be added:

Fund type	varchar(50)	Whether the payment is splitted into difference account:	`NonSplittingOrder	`NonSplittingOrder
		SplittingOrder
		NonSplittingOrder
Fee RMB	varchar(255) Floating-point string, retain 5 decimal places	Fee charged/refunded by the Wechat Pay for processing the transaction (in CNY).	`2.50000	`2.50000
Refund account	varchar(50)	The funding source of the refund, possible values are:	`	`UnsettledFund
		UnsettledFund，the fund not yet settled
		RechargeFund, the fund manually added by the merchant

Response for failed request:

Name

Variable Name

Type

Required

Description

Returned status code

code

string[1,32]

Yes

Error code. See the error code list for the enumerated values.

Returned information

message

string[1,256]

Yes

Returned message. It indicates the reason for the error if not empty.

Detailed error description

detail

object

It is returned when code is PARAM_ERROR. Details will be described below.

Detailed error description

Response Example:

ERROR

1{
2	"code": "INVALID_REQUEST",
3	"message": "Parameter format verification error",
4	"detail": {
5		"field": "#/properties/payer",
6		"value": "1346177081915535577",
7		"issue": "与ALLOF schema不符",
8		"location": "body"
9	}
10}

4. Response Signature Verification Description

4.1. Construct a signature string

First, get the response random string in theHTTP header Wechatpay-Nonce, the response timestamp in Wechatpay-Timestamp, and the bill SHA1 value in Wechatpay-Statement-Sha1 from the response.

Construct a response signature string by following the rules below. \n is a line break (ASCII code is 0x0A).

1    Response timestamp\n
2    Response random string\n
3    Bill SHA1\n
4    \n

Then, the signature string is:

1    1507709906
2    5K8264ILTKch16CQ2502SI8ZNMTM67VS
3    {"sha1" : "12345678999"}

Tips：

the sha1 value in red is specially processed in JSON format for signature.

4.2. Get the response signature

A WeChat Pay response signature is passed via Wechat-Signature in the HTTP header. (Note: line breaks exist in the example for typesetting, but in practice the data should be put in a single line.) Wechatpay-Signature: WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAl wmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=，Decode the field value of Wechatpay-Signature with Base64 to get the response signature.

4.3. Verify the signature

The signature can be verified with signature functions in many programming languages. A merchant is recommended to call this type of function, and verify the signature string with SHA256-with-RSA signature algorithm using the WeChat Pay Platform public key.

f the programming language or library used by the merchant only supports signature verification for the digest data, follow the steps below to verify the signature:

Calculate the digest of the signature string with SHA256.
Verify the RSA signature of the digest using the WeChat Pay Platform public key (signature type is SHA256). For more information, please see RSA_verify() of OpenSSL.

Tips：

The serial number of the WeChat Pay certificate is in the HTTP header `Wechatpay-Serial`. Before verifying the signature, check that this serial number is consistent with that of the WeChat Pay certificate held by the merchant. For details on the certificate update, please see "Get WeChat Pay Platform Certificate".

4.4. Verify the bill integrity

After the bill is completely downloaded and the SHA1 signature is generated, compare the signature with the Wechatpay-Statement-Sha1 value for bill integrity check.

5. Error Codes

Error Message	Description	Solution
SYSTEM_ERROR	WeChat Pay internal error	Try again later
PARAM_ERROR	Invalid parameter	Check parameters based on the request parameter description of the document.
NO_STATEMENT_EXIST	The bill does not exist.	Check whether any funds changes occur to the WeChat account of the current Merchant ID within the specified date.
BILL_CREATING	Bill in generating	Check whether there are any successful transactions under the current Merchant ID within the specified date. If there is a transaction on the specified date, the bill is being generated. Download it after 10 am.