查询结算资金明细

更新时间：2025.01.07

商户在交易完结之后，可按结算日期查询已结算资金明细（sette_state为SETTLED），也可以查询未结算资金明细（sette_state为UNSETTLE）。

注意：

该接口供跨境收单机构/直连商户使用，特别是，日本/澳门机构商户若开通香港钱包业务，需要对接该接口。

1. 接口说明

适用对象：直连模式机构模式

接口URL：https://apihk.mch.weixin.qq.com/v3/global/settle/settlements

请求方式：GET

Path 指该参数为路径参数

Query 指该参数为URL参数

Body 指该参数需在请求JSON传参

2. 请求参数

参数名	变量	类型	必填	描述
子商户号	sub_mchid	string（32）	否	Query 子商户，填写微信支付分配的商户号 1、若商户是直连商户、机构/银行服务商，无需填写该字段 2、若商户是普通服务商商户，需要填写该字段示例值：1900000101
结算状态	settle_state	string（32）	是	Query 资金结算状态，枚举值： SETTLED：已结算 UNSETTLE：未结算示例值：SETTLED
结算开始日期	settle_start_date	string（8）	否	Query 1、格式为yyyyMMdd，如2009年12月25日表示为20091225，时区为GMT+8 beijing 2、当settle_state（结算状态）为SETTLED时，该字段必填；示例值：20091225
结算结束日期	settle_end_date	string（8）	否	Query 1、格式为yyyyMMdd，如2009年12月25日表示为20091226，时区为GMT+8 beijing 2、当settle_state（结算状态）=SETTLED时，该字段必填； 3、结算结束日期需大于等于结算开始日期示例值：20091226
最大记录条数	limit	uint32	是	Query 返回的最大记录条数，一般不超过10条为佳，系统最大支持30条示例值：5
记录起始位置	offset	uint32	是	Query 该次请求资源的起始位置示例值：10

请求示例：

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. 返回参数

参数名

变量

类型[长度限制]

必填

描述

结算信息列表

data

array

是

结算信息的详情

结算信息列表

参数名

变量

类型[长度限制]

必填

描述

付款批次号

batch_id

string[1,32]

是

微信返回的付款批次号

示例值：20091225003

结算日期

settlement_date

string[1,8]

是

格式为yyyyMMdd，如2009年12月25日表示为20091225。时区为GMT+8 beijing

示例值：20091225

交易开始日期

trade_start_date

string[1,8]

是

格式为yyyyMMdd，如2009年12月25日表示为20091226。时区为GMT+8 beijing

示例值：20091225

交易结束日期

trade_end_date

string[1,8]

是

格式为yyyyMMdd，如2009年12月25日表示为20091225。时区为GMT+8 beijing

示例值：20091225

金额

amount

object

是

指未特殊标记为分账类的普通跨境收单交易。

金额

钱包主体

wallet_region

string

否

日本/中国澳门区域已经开通微信香港钱包的跨境收单商户，该字段取值如下：
CHINA_MAINLAND：中国大陆钱包
CHINA_HONGKONG：中国香港钱包
其他场景的商户不返回该字段。

示例值：CHINA_HONGKONG

分账业务金额

split_amount

object

否

指已标记为分账类的跨境收单交易，适用于开通分账功能的业务场景。微信支付平台仅针对特定行业开放分账能力（如跨境电商行业），具体以平台对外公布的产品信息为准。

分账业务金额

总记录条数

total_count

int

是

资源总条数。当offset=0或者当前查询为空时应该返回总条数
示例值：1234

记录起始位置

offset

int

是

示例值：1

本次返回条数

limit

int

是

示例值：20

返回示例

正常示例

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}

4. 错误码

错误码	描述	解决方案
SYSTEM_ERROR	系统错误	系统错误，请稍后再试
PARAM_ERROR	参数错误	参数错误，请核对参数后重试
FREQUENCY_LIMITED	请求频率过高	请求频率过高，请稍后重试
RESOURCE_NOT_EXISTS	记录不存在	记录不存在，请调整参数后重试