Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

Query Fund Settlement Details

Latest update time:2021.12.14 Release notes


After a transaction has been closed, 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.

API intro

Request Url:https://api.mch.weixin.qq.com/hk/v3/settle/settlements

Request method:GET

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

Applicable object:Common modeInstitutional mode


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
Sub-merchant ID sub_mchid string(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(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(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(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

Example:


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

Return Data

Normal return

Name Variable Name Type Required Description
+Settlement Information List data array No Details of the settlement information
Name Variable Name Type Required Description
Batch Number batch_id string(32) Yes Batch number by WeChat
Example:20091225003
Settlement Date settlement_date string(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(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(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(16) Yes Currency, The three letter code in accordance with ISO 4217
Example:HKD
Payment Amount pay int Yes Priced in foreign currency at the minimum trading unit
Example:123
Refund Amount refund int Yes Priced in foreign currency at the minimum trading unit
Example:123
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
Wallet Region wallet_region string(32) No 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 No 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
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

Example:


{
  "data": [
    {
      "amount": {
        "currency": "HKD",
        "fee": 123,
        "net": 123,
        "pay": 123,
        "refund": 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
}
 
                                

Release notes

close
V1.1
2022.03.02
1. Added new fields in response parameteres:split_amount(Amount of Funds-distribution)
V1.0
2021.12.14
1. Query Fund Settlement Details API released online

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global