最新更新时间：2022.4.6 版本说明
商户可以通过该接口查询转账批次单以及指定状态的转账明细单。
• API只支持查询最近30天内的转账批次单，30天之前的转账批次单请登录商户平台查询。
• 转账明细单只会在批次单完成的情况下返回，如果需要在批次处理过程中查询转账明细单，请通过转账明细单查询接口来查询。
• 转账批次单中涉及金额的字段单位为“分”。
• 如果查询单号对应的数据不存在，那么数据不存在的原因可能是：
（1）批次还在受理中；
（2）批次受理失败导致转账批次单没有落地。
在上述情况下，商户首先需要检查该商家批次单号是否确实是自己发起的，如果商户确认是自己发起的，则请商户不要直接当做受理失败处理，请商户隔几分钟再尝试查询（请勿转账和查询并发处理），或者商户可以通过相同的商家批次单号再次发起转账。如果商户误把还在受理中的批次单直接当受理失败处理，商户应当自行承担因此产生的所有损失和责任。
适用对象：直连商户
请求URL：https://api.mch.weixin.qq.com/v3/transfer/batches/batch-id/{batch_id}
请求方式：GET
接口限频： 单个商户 50QPS，如果超过频率限制，会报错FREQUENCY_LIMITED，请降低频率请求。
path指该参数为路径参数
query指该参数需在请求URL传参
body指该参数需在请求JSON传参
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 微信批次单号 | batch_id | string[1,64] | 是 | path微信批次单号，微信商家转账系统返回的唯一标识 示例值：1030000071100999991182020050700019480001 |
| 是否查询转账明细单 | need_query_detail | boolean | 是 | query枚举值： true：是； false：否，默认否。 商户可选择是否查询指定状态的转账明细单，当转账批次单状态为“FINISHED”（已完成）时，才会返回满足条件的转账明细单 示例值：true |
| 请求资源起始位置 | offset | int | 否 | query该次请求资源的起始位置，从0开始，默认值为0 示例值：1 |
| 最大资源条数 | limit | int | 否 | query该次请求可返回的最大明细条数，最小20条，最大100条，不传则默认20条。不足20条按实际条数返回 示例值：20 |
| 明细状态 | detail_status | string[1,32] | 否 | query查询指定状态的转账明细单，当need_query_detail为true时，该字段必填 ALL:全部。需要同时查询转账成功和转账失败的明细单 SUCCESS:转账成功。只查询转账成功的明细单 FAIL:转账失败。需要通过查询明细单接口确认明细失败原因后，再决定是否重新发起对该笔明细单的转账（并非整个转账批次单） 示例值：FAIL |
https://api.mch.weixin.qq.com/v3/transfer/batches/batch-id/10300000711009999911?need_query_detail=true&detail_status=ALL
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| +转账批次单 | transfer_batch | object | 是 | 转账批次单基本信息 |
| +转账明细单列表 | transfer_detail_list | array | 否 | 当批次状态为“FINISHED”（已完成），且成功查询到转账明细单时返回。包括微信明细单号、明细状态信息 |
{
"transfer_batch": {
"mchid": "1900001109",
"out_batch_no": "plfk2020042013",
"batch_id": "1030000071100999991182020050700019480001",
"appid": "wxf636efh567hg4356",
"batch_status": "ACCEPTED",
"batch_type": "API",
"batch_name": "2019年1月深圳分部报销单",
"batch_remark": "2019年1月深圳分部报销单",
"close_reason": "OVERDUE_CLOSE",
"total_amount": 4000000,
"total_num": 200,
"create_time": "2015-05-20T13:29:35.120+08:00",
"update_time": "2015-05-20T13:29:35.120+08:00",
"success_amount": 3900000,
"success_num": 199,
"fail_amount": 100000,
"fail_num": 1
},
"transfer_detail_list": [
{
"detail_id": "1040000071100999991182020050700019500100",
"out_detail_no": "x23zy545Bd5436",
"detail_status": "SUCCESS"
}
]
}
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 500 | SYSTEM_ERROR | 系统错误 | 5开头的状态码都为系统问题，请使用相同参数稍后重新调用 |
| 404 | NOT_FOUND | 记录不存在 | 查询的转账批次单不存在 |
| 429 | FREQUENCY_LIMITED | 频率超限 | 请求量不要超过接口调用频率限制 |
| 400 | PARAM_ERROR | 参数错误 | 根据错误提示，传入正确参数 |
| INVALID_REQUEST | 请求参数符合参数格式，但不符合业务规则 | 查询单据超过限定时间(30天)，可以尝试通过商户平台预约下载 |