Query Fund Settlement Details

Update Time：2025.01.07

The merchant can query the details of both settled funds (sette_state is SETTLED) and unsettled funds (sette_state is UNSETTLE) by settlement date.

Tips：

This API is available to cross-border acquiring institutions/direct merchants. Particularly, Japanese/Macau institutions that have activated Hong Kong Wallet should use this API.

1. API intro

Applicable object： Common mode Institutional mode

Request Url：https://apihk.mch.weixin.qq.com/v3/global/settle/settlements

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
Sub-merchant ID	sub_mchid	string[1,32]	No	Query 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 Example: 1900000101
Settlement Status	settle_state	string[1,32]	Yes	Query Fund settlement status. Enumerated values: SETTLED: Funds are settled UNSETTLE: Funds are not settled Example: SETTLED
Settlement Start Date	settle_start_date	string[1,8]	No	Query Format: yyyyMMdd, such as 20091225 for Dec. 25, 2009. Time zone: GMT+8 Beijing. If settle_state is SETTLED, this field is required. If settle_state is UNSETTLE, this field is invalid. Example: 20091225
Settlement End Date	settle_end_date	string[1,8]	No	Query Format: yyyyMMdd, such as 20091226 for Dec. 26, 2009. Time zone: GMT+8 Beijing. If settle_state is SETTLED, this field is required. If settle_state is UNSETTLE, this field is invalid. The settlement end data must be later than the settlement start date. Example: 20091226
Maximum Count	limit	int	Yes	Query The maximum number of records returned, which is preferably 10 or less. The system supports up to 30 records. Example: 5
Start Position of Record	offset	int	Yes	Query The start position of the requested resources. Example: 10

Request Example

URL

1https://apihk.mch.weixin.qq.com/v3/global/settle/settlements?sub_mchid=190000010&settle_state=SETTLED&settle_start_date=20091225&settle_end_date=20091226&offset=10&limit=5

3. Response Parameters

Name	Variable Name	Type	Required	Description
Settlement Information List	data	array	No	Details of the settlement information
Total Count	total_count	int	Yes	Total number of resources. If offset is 0 or no record is found for this query, this parameter is returned. Example: 123
Start Position of Record	offset	int	Yes	The start position of the resources for this query Example: 1
Records Returned	limit	int	Yes	The number of records found for this query is returned. Example: 20

Return Example

SUCCESS

1{
2  "data": [
3    {
4      "amount": {
5        "currency": "HKD",
6        "fee": 123,
7        "net": 123,
8        "settled": 123,
9        "unsettle": 123
10      },
11      "batch_id": "20091225003",
12      "settlement_date": "20091225",
13      "split_amount": {
14        "currency": "HKD",
15        "pay": 123,
16        "refund": 123,
17        "settled": 123,
18        "unsettle": 123
19      },
20      "trade_end_date": "20091225",
21      "trade_start_date": "20091225",
22      "wallet_region": "CHINA_HONGKONG"
23    }
24  ],
25  "limit": 20,
26  "offset": 1,
27  "total_count": 1234
28}

ERROR

1{
2	"code": "SYSTEM_ERROR",
3	"message": "Parameter error"
4}

4. Error Code

Error Message	Description	Solution
SYSTEM_ERROR	System error	System error. Try again later.
PARAM_ERROR	Parameter error	Parameter error. Check it and try again.
FREQUENCY_LIMITED	Too many attempts	Too many attempts. Try again later.
RESOURCE_NOT_EXISTS	Record not found	Record not found. Modify the parameter and try again.