WeChat Pay Open Platform

返回上一层 Home / Multi-Wallet ( For HK) / QR Code Payment / Downloading Reconciliation API

Downloading Reconciliation API

Latest update time：2024.03.20 Release notes

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.

Notes:

1. 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.

2. Billing compression: To compress the bill, set the request as gzip via the HTTP header Accept-Encoding.

API intro

Request URL:

https://api.mch.weixin.qq.com/hk/v3/statements

Request method: GET

Applicable object:Common modeInstitutional mode

API Rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3

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.

Request Parameters

Name	Variable Name	Type	Required	Description
Bill date	date	string(8)	Yes	query Bill date in the format of 20180103 Example：20180130
Merchant ID	mchid	string(32)	No	query Merchant ID assigned by WeChat Pay Example：1900000109

For example：


https://api.mch.weixin.qq.com/hk/v3/statements?date=20180130&mchid=1900000109

    
｛
JAVA示例代码
｝

Returned Result

Response for failed request

Name

Variable Name

Type

Required

Description

Returned status code

code

string(32)

Yes

Error code. See the error code list for the enumerated values.
Example：INVALID_REQUEST

Returned information

message

string(256)

Yes

Returned message. It indicates the reason for the error if not empty.
Example：Parameter format verification error

+Detailed error description

detail

object

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

Name	Variable Name	Type	Required	Description
Location of the incorrect parameter	field	string(256)	Yes	If the incorrect parameter is in the JSON for request body, it is populated with the JSON Pointer pointing to this parameter. If the incorrect parameter is in the request URL or querystring, it is populated with the variable name of this parameter. Example：#/properties/payer
Value of the incorrect parameter	value	string(256)	Yes	Value of the incorrect parameter Example：1346177081915535577
Cause of error	issue	string(256)	Yes	Cause of error It is different from ALLOF schema
Location of the incorrect parameter	location	string(256)	No	body：The incorrect parameter is in the JSON for request body url：The incorrect parameter is in the request URL query：The incorrect parameter is in the querystring of the request Example：body

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.

1）The first row is the header.The detailed fields are as follows:

Field Name	Payment Example	Refund Example	Field Description
Transaction Time	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)	`wx87b0b4160031234	`wx87b0b4160031234	Wechat Pay's unique reference associated with the Wechat offcial account or Wechat micro app.
Vendor ID(mchid)	`123450000	`123450000	Wechat Pay's unique MerchantId attributed to each merchant
Sub vendor ID(sub_mchid)	`600000001	`600000001	Wechat Pay's unique sub merchant id attributed to each sub-merchant
Device ID(device_id)	`013467007045764	`013467007045764	ID of the terminal where the transaction occurred ( as sent in the original payment request, can have blanks)
Wechat Order Number(transaction_id)	`4200002158202403119854123456	`4200002158202403119854123456	Wechat Pay's unique reference associated with the transaction.
Vendor Order Number(out_trade_no)	`20240311105346P3791	`20240311105346P3791	Your reference for the transaction. This is the out_trade_no from the original payment request.
User Tag(openid)	`oZPPassSdACFwnRNEVQVAkvj_5NU	`oZPPassSdACFwnRNEVQVAkvj_5NU	The unique identifier of the payer in the payment transaction.
Transaction Type(trade_type)	`NATIVE	`NATIVE	The type of transaction. Possible values are: MICROPAY JSAPI NATIVE APP FACE
Transaction Status(trade_state)	`SUCCESS	`REFUND	The type of transaction. Possible values are: SUCCESS，representing a payment transaction REFUND, representing a refund transaction
Payment Bank(bank_type)	`CMB_CREDIT	`CMB_CREDIT	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
Top-up Voucher Currency Type	`	`	Coupon Currency（quotation currency）
Top-up Voucher Amount	`0.00	`0.00	Coupon amount （in quotation currency)
Coupon Currency Type	`	`	NOT APPLICABLE
Coupon Amount	`0.00	`0.00	NOT APPLICABLE
Wechat Refund Number(refund_id)	`	`50202407752024031135708554321	Wechat Pay's unique reference associated with the refund. The value is 0 if the transaction is a payment.
Vendor Refund Number(out_refund_no)	`	`20240311459568556791724321	Your reference for the refund. The value is 0 if the transaction is a payment.
Refund Channel	`	`ORIGINAL	ORIGINAL--refund to the original payment method BALANCE-refund to Wechat Pay balance null if the transaction is a payment
Refund Status	`	`SUCCESS	Refund status when the transaction report is generated, which won't update. Possible values are: SUCCESS PROCESSING
Product Name(description)	`E8D253EF9036	`E8D253EF9036	This is the "body" from the original payment request.
Merchant's Data Package(attach)	`3EF9E1D25036	`3EF9E1D25036	This is the "attach" from the original payment request. It is not unique and can have blanks.
Fee	`0.33000	`-0.08000	Fee charged/refunded by the Wechat Pay for processing the transaction(in settlement currency).
Rate	`0.50%	`0.50%	Fee rate
Transaction Currency Type	`HKD	`HKD	Three character ISO code for the currency which was used for processing the payment (quotation currency)
Transaction Amount(total)	`65.66	`0.00	Gross payment amount in quotation currency. The value is 0.00 if the transaction is a refund.
Payer Currency Type(payer_currency)	`CNY	`CNY	Three character ISO code for the currency which was used for processing the payment (payment currency)
Payer Payment Amount(payer_total)	`60.45	`0.00	The amount paid by the user.
Settlement Currency Type	`HKD	`HKD	Three character ISO code for the currency which was used for processing the payment (settlement currency)
Settlement Currency Amount	`65.66	`0.00	Transaction amount in settlement currency. The value is 0.00 if the transaction is a refund.
Transaction Exchange Rate	`92067840	`92067840	Exchange rate used for converting the Cash payment amount into the Settlement currency amount.
Refund Exchange Rate	`0	`0	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.
Refund Amount	`0	`16.00	Refund amount (quotation currency)
Payer Refund Currency Type	`	`CNY	Three character ISO code for the currency which was used for processing the refund (payment currency)
Payer Refund Amount	`0	`14.73	The amount refund to the user. The value is 0.00 if the transaction is a payment.
Refund Settlement Currency Type	`	`HKD	Three character ISO code for the currency which was used for processing the refund (settlement currency)
Refund Amount for merchant in settlement currency	`0	`16.00	Transaction amount in settlement currency The value is 0.00 if the transaction is a payment.
Refund Amount of Top-up Voucher	`0	`0.00	The amount refund to the coupon account.
Refund Amount of Coupon	`0	`0.00	NOT APPLICABLE
Fund type	`NonSplittingOrder	`NonSplittingOrder	Whether the payment is splitted into difference account: SplittingOrder NonSplittingOrder
Fee RMB	`0.14000	`0.07000	Fee charged/refunded by the Wechat Pay for processing the transaction (in CNY).
Refund account	`	`UnsettledFund	The funding source of the refund, possible values are: UnsettledFund，the fund not yet settled RechargeFund, the fund manually added by the merchant

2）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.

For example:

ERROR

{
      "code" : " NO_STATEMENT_EXIST",
      "message" : "The bill does not exist."
 ｝

{
｛
      "code" : " NO_STATEMENT_EXIST",
      "message" : "The bill does not exist."
    ｝

Response Signature Verification Description

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).

Response timestamp\n
Response random string\n
Bill SHA1\n
\n

Then, the signature string is:


    1507709906
    5K8264ILTKCH16CQ2502SI8ZNMTM67VS
    {"sha1" : "12345678999"}

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

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/Asl93jo
TW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=，Decode the field value of Wechatpay-Signature with Base64 to get the response signature.

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:

1.Calculate the digest of the signature string with SHA256.

2.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.

Note: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".

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.

Error Codes

Error Codes	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.

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

QR Code Payment

Downloading Reconciliation API

Notes:

API intro

Request Parameters

For example：

Returned Result

Response for failed request

Response for successful request

For example:

Response Signature Verification Description

Construct a signature string

Get the response signature

Verify the signature

Verify the bill integrity

Error Codes

Release notes