API Dictionary / In-App Payment / Query Fund Settlement Details API

Query Fund Settlement Details

Latest update time：2023.04.21 Release notes

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

Pathparameter is a path parameter.

Queryparameter needs to be passed in the request URL.

Bodyparameter 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	QueryThe 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 Eample

URL


https://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


									{
										"stock_id": "PHP",
										"offset": 10,
										"limit": 10,
									}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

3. Response Parameters

Name

Variable Name

Type

Required

Description

Settlement Information List

data

array

Details of the settlement information

Name

Variable Name

Type

Required

Description

Batch Number

batch_id

string[1,32]

Yes

Batch number by WeChat
Example: 20091225003

Settlement Date

settlement_date

string[1,8]

Yes

The format is yyyymmdd, for example, December 25, 2009 is 20091225, and the time zone is GMT + 8 Beijing
Example: 20091225

Trade Start Date

trade_start_date

string[1,8]

Yes

The format is yyyymmdd, for example, December 25, 2009 is 20091225, and the time zone is GMT + 8 Beijing
Example: 20091225

Trade End Date

trade_end_date

string[1,8]

Yes

The format is yyyymmdd, for example, December 25, 2009 is 20091225, and the time zone is GMT + 8 Beijing
Example: 20091225

Amount

amount

object

Yes

settlement amount

Name	Variable Name	Type	Required	Description
Settled Amount	settled	int	Yes	Priced in foreign currency at the minimum trading unit Example: 123
Unsettle Amount	unsettle	int	Yes	Priced in foreign currency at the minimum trading unit amount is summarized for settlement by day. When the refund amount is greater than the payment amount, this value may be negative. Calculation formula: Unsettled amount = Payment amount - Refund amount - Handling fee amount. Example: 123
Currency	currency	string[1,16]	Yes	Currency, The three letter code in accordance with ISO 4217 Example: HKD
Net Amount	net	int	Yes	Priced in foreign currency at the minimum trading unit amount may be negative. (The amount is summarized for settlement by day. When the refund amount is greater than the payment amount, this value may be negative. Calculation formula: Net payment = Payment amount - Refund amount) Example: 123
Fee	fee	int	Yes	Priced in foreign currency at the minimum trading unit amount may be negative. (The amount is summarized for settlement by day. When the refund amount is greater than the payment amount, this value may be negative. ) Example: 123

pack up

Wallet Region

wallet_region

string[1,32]

For overseas merchants who have opened WeChat Hong Kong wallet in Japan/Macao(China), the values of this field are as follows:， CHINA_MAINLAND
CHINA_HONGKONG
Note: Merchants in other scenarios do not return this field
Example: CHINA_HONGKONG

Amount of Funds-distribution

split_amount

object

Refers to the cross-border acquisition transactions marked as the funds-distribution type, applicable to business scenarios where the funds-distribution function is enabled. The WeChat Pay platform only enables the funds-distribution capability for specific industries (such as the cross-border e-commerce industry) only, subject to the product information published by the platform.

Name	Variable Name	Type	Required	Description
Settled Amount	settled	int	Yes	Transaction Start Date to Transaction End Date Summary of Settled Amount Minimum Unit of Currency Example: 123
Unsettled Amount	unsettle	int	Yes	Transaction Start Date to Transaction End Date Summary of Unsettled Amount Minimum Unit of Currency (For summarizing and settling by day, if the refund amount is greater than the payment amount, this value may be negative. Calculation formula: Unsettled Amount = Payment Amount - Refund Amount - Service Fee Amount) Example: 123
Settlement Currency	currency	string[3, 3]	Yes	Currency, a three letter code in compliance with the ISO 4217 standard Example: HKD
Payment Amount	pay	int	Yes	Transaction Start Date to Transaction End Date Total Payment Amount Minimum Unit of Currency Example: 123
Refund Amount	refund	int	Yes	Transaction Start Date to Transaction End Date Total Refund Amount Minimum Unit of Currency Example: 123

pack up

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 ERROR


{
  "data": [
    {
      "amount": {
        "currency": "HKD",
        "fee": 123,
        "net": 123,
        "settled": 123,
        "unsettle": 123
      },
      "batch_id": "20091225003",
      "settlement_date": "20091225",
      "split_amount": {
        "currency": "HKD",
        "pay": 123,
        "refund": 123,
        "settled": 123,
        "unsettle": 123
      },
      "trade_end_date": "20091225",
      "trade_start_date": "20091225",
      "wallet_region": "CHINA_HONGKONG"
    }
  ],
  "limit": 20,
  "offset": 1,
  "total_count": 1234
}


{
	"code": "SYSTEM_ERROR",
	"message": "Parameter error"
}


									{
										"stock_id": ".NET",
										"limit": 10,
									}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

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.

Page Navigation

Language

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Payments

Funding Products

Other Products

Query Fund Settlement Details

1. API intro

2. Request Parameters

Request Eample

3. Response Parameters

Return Example

4. Error Code