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

  1. Format: yyyyMMdd, such as 20091225 for Dec. 25, 2009. Time zone: GMT+8 Beijing.

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

  1. Format: yyyyMMdd, such as 20091226 for Dec. 26, 2009. Time zone: GMT+8 Beijing.

  2. If settle_state is SETTLED, this field is required. If settle_state is UNSETTLE, this field is invalid.

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

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.