Latest update time：2019.11.20 Release notes
This API helps query the details of settled funds.
1. If sub merchants need to call this API, mch_id could be set as their sub merchant ID. And appid could be set as either the sub official account ID or official account ID.
Request Url: https://api.mch.weixin.qq.com/pay/settlementquery
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: Wx1378acui7865dt65 |
| Merchant ID | mch_id | String(32) | Yes | Specifies merchant ID assigned by WeChat Pay Example: 12567876549 |
| Sub Merchant ID | sub_mch_id | String(32) | Yes | The merchant ID assigned by WeChat Pay for the sub-merchant 1.For direct merchants or institutions, this field is not required 2.For service providers, this field is required Note: Only for Institutional mode Example: 12567876549 |
| Settlement Status | usetag | int | Yes | Indicates the fund has been settled or is still outstanding: 1 - settled 2 – outstanding Example: 1 |
| Random String | nonce_str | String(32) | Yes | A random string of less than 32 chars. For more information, see Random String Algorithm. Example: Uihu276jjghxlehu38764409322 |
| Offset | offset | int | Yes | Returned query data starts from this offset value Example: 0 |
| Max Records | limit | int | Yes | The number of returned records (generally less than 10) Example: 10 |
| Start Date | date_start | String(14) | Yes | In the format of yyyyMMdd. For example, December 25, 2009 is expressed as 20091225 in the time zone (GMT+8). For more information, see Time Protocol. Example: 20150807 |
| End Date | date_end | String(14) | Yes | In the format of yyyyMMdd. For example, December 25, 2009 is expressed as 20091225 in the time zone (GMT+8). For more information, see Time Protocol. Example: 20150807 |
| Whether to query funds-distribution settlement information | query_split | bool | No | or merchants with enabled funds-distribution permission, if query_split is true, the funds-distribution settlement field will be added to the returned information; merchants without funds-distribution permission do not need to check this field. Example：true |
| Signature | sign | String(64) | Yes | Specifies a signature. For more information, see Signature Algorithm. Example: 8439EBD8AE7422590E2004D0C5EBFFBC |
<xml>
<appid>wx2421b1c4370ec43b</appid>
<mch_id>10000100</mch_id>
<usetag>1</usetag>
<nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>
<offset>1</offset>
<limit>10</limit>
<date_start>20150807</date_start>
<date_end>20150807</date_end>
<sign>FDD167FAA73459FD921B144BAF4F4CA2</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 | SUCCESS/FAIL Specifies communicating label (not transaction label). The status of a transaction is determined by the value of result_code. Example: SUCCESS |
| Return Data | return_msg | String(128) | NO | If returned data is not empty, the returned data is the error description of the following: - Signature Failure - Parameter format checking error Example: Signature failure |
If return_code is SUCCESS, return data will also include the following fields:
| 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 Pay Example: wx8888888888888888 |
| Sub Merchant ID | sub_mch_id | String(32) | Yes | Specifies sub merchant ID assigned by WeChat Pay Specifies Sub merchant ID of institution's sub-merchant assigned by WeChat Pay Note: Only for Institutional mode Example: 1900000109 |
| Random String | nonce_str | String(32) | Yes | Indicates a random string of less than 32 chars Example: 5K8264ILTKCH16CQ2502SI8ZNMTM67VS |
| Service Result | result_code | String(16) | Yes | SUCCESS/FAIL Example: SUCCESS |
| Error Code | err_code | String(32) | No | ORDERNOTEXIST: Order does not exist SYSTEMERROR: System error Example: SYSTEMERROR |
| Error Code Description | err_code_des | String(128) | No | Describes result data Example: System error |
| Return Data Lines | record_num | String(10) | Yes | Indicates the number of lines of return data. And the following fields would be returned when result_code is SUCCESS and record_num is not 0. |
The following fields will be returned when result_code is SUCCESS. In case of multiple records, the data will be repeated.
| Name | ID | Type | Required | Description |
|---|---|---|---|---|
| Foreign Payment Batch Number | fbatchno | String(32) | Yes | Indicates the batch number of foreign payment Example: 10 |
| Settlement Date | date_settlement | String(14) | Yes | In the format of yyyyMMdd. For example, December 25, 2009 is expressed as 20091225 in the time zone (GMT+8). Example: 20091225 |
| Transaction Start Date | date_start | String(14) | Yes | In the format of yyyyMMdd. For example, December 25, 2009 is expressed as 20091225 in the time zone (GMT+8). Example: 20091225 |
| Trasanction End Date | date_end | String(14) | Yes | In the format of yyyyMMdd. For example, December 25, 2009 is expressed as 20091225 in the time zone (GMT+8). Example: 20091225 |
| Remit Amount | settlement_fee | String(32) | Yes | Priced in foreign currency at the minimum trading unit Example: 1 |
| Non-Remit Amount | unsettlement_fee | String(32) | Yes | Priced in foreign currency at the minimum trading unit Example: 1 |
| Settlement Currency | settlementfee_type | String(8) | Yes | Comply with ISO 4217 standards and use CNY for Chinese currency by default. Notes: The currency type for payment and refund shall be the same. Example: GBP |
| Payment Amount | pay_fee | int | Yes | Priced in foreign currency at the minimum trading unit Example: 1 |
| Refund Amount | refund_fee | int | Yes | Priced in foreign currency at the minimum trading unit Example: 1 |
| Net Payment Amount | pay_net_fee | int | Yes | Priced in foreign currency at the minimum trading unit Example: 1 |
| Charge Amount | poundage_fee | int | Yes | Priced in foreign currency at the minimum trading unit Example: 1 |
| Funds-distribution transfer amount | split_settlement_fee | int | No | foreign currency price, in the minimum unit of foreign currency. The information will be returned when the merchant enables funds-distribution permission, [query_split=true], and [usetag=1]. Example：1 |
| Not-transferred amount in funds-distribution | split_unsettlement_fee | int | No | Not-transferred amount in funds-distribution:
foreign currency price, in the minimum unit of foreign currency. The information will be returned when the merchant enables funds-distribution permission, [query_split=true], and [usetag=2]. Example：1 |
<xml>
<return_code>SUCCESS</return_code>
<result_code>SUCCESS</result_code>
<appid>wx2421b1c4370ec43b</appid>
<mch_id>10000100</mch_id>
<record_num>10</record_num>
<nonce_str>ec2316275641faa3aacf3cc599e8730f</nonce_str>
<fbatchno>10</fbatchno>
<date_settlement>20150807</date_settlement>
<date_start>20150807</date_start>
<date_end>20150807</date_end>
<sign>FDD167FAA73459FD921B144BAF4F4CA2</sign>
<settlement_fee>1000</settlement_fee>
<unsettlement_fee>0</unsettlement_fee>
<settlement_type>USD</settlement_type>
<pay_fee>1000</pay_fee>
<refund_fee>0</refund_fee>
<pay_net_fee>1000</pay_net_fee>
<poundage_fee>0</poundage_fee>
</xml>
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证