微信支付转账批次单号查询批次单

更新时间：2025.03.11

微信商家转账批次单号查单接口。商户可以通过该接口查询转账批次单以及指定状态的转账明细单。返回消息中包含微信批次单号、批次状态、批次类型、转账总金额、转账总笔数、成功金额、失败金额等信息。

接口说明

支持商户：【平台商户】

请求方式：【GET】/v3/platsolution/insurance/mch-transfer/batches/batch-id/{batch_id}

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引点击查看

请求参数

Header HTTP头参数

Authorization 　必填　string

请参考签名认证生成认证信息

Accept 　必填　string

请设置为application/json

path 路径参数

batch_id 　必填 string(64)

【商家转账批次单号】商家转账批次单号，微信商家转账系统返回的唯一标识

query 查询参数

sub_mchid 　必填 string(32)

【二级商户号】二级商户号

need_query_detail 　必填 boolean

【是否查询转账明细单】 true-是；false-否，默认否。商户可选择是否查询指定状态的转账明细单，当转账批次单状态为“FINISHED”（已完成）时，才会返回满足条件的转账明细单

offset 　选填 integer

【请求资源起始位置】该次请求资源的起始位置。返回的明细是按照设置的明细条数进行分页展示的，一次查询可能无法返回所有明细，我们使用该参数标识查询开始位置，默认值为0

limit 　选填 integer

【最大资源条数】该次请求可返回的最大明细条数，最小20条，最大100条，不传则默认20条。不足20条按实际条数返回

detail_state 　选填 string

【明细状态】查询指定状态的转账明细单。

可选取值

ALL: 全部。查询批次下所有明细单
WAIT_PAY: 待二级商户员工（转账验密人）确认, 符合免确认条件时, 系统会自动扭转为转账中
SUCCESS: 转账成功
FAIL: 需要确认失败原因后，再决定是否重新发起对该笔明细单的转账（并非整个转账批次单）
BANK_REFUND: 银行返回转账成功后，拒绝入账，资金会返回商户账户。

请求示例

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/platsolution/insurance/mch-transfer/batches/batch-id/131000011085109987515042023022300246500006?sub_mchid=1900102208&need_query_detail=true&offset=0&limit=20&detail_state=ALL \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" 
5

应答参数

200 OK

transfer_batch 　必填 object

【转账批次单】转账批次单基本信息

属性

out_batch_no 　必填 string(32)

【商家批次单号】服务商系统内部的批次单号，在服务商系统内部唯一

batch_id 　必填 string(64)

【商家转账批次单号】商家转账批次单号，微信商家转账系统返回的唯一标识

sp_appid 　必填 string(32)

【服务商应用ID】微信分配的商户公众账号ID

sub_mchid 　必填 string(32)

【二级商户号】二级商户号

sub_appid 　选填 string(32)

【二级商户应用ID】微信分配的商户公众账号ID

batch_state 　必填 string

【批次状态】商家转账批次单状态

可选取值

ACCEPTED: 批次已受理成功，若发起批量转账的30分钟后，转账批次单仍处于该状态，可能原因是出资商户账户余额不足等。商户可查询账户资金流水，若该笔转账批次单的扣款已经发生，则表示批次已经进入转账中，请再次查单确认
PROCESSING: 已开始处理批次内的转账明细单
COMPLETED: 批次内的所有转账明细单都已处理完成
CLOSED: 可根据 close_reason 字段确认具体的批次关闭原因确认

batch_name 　必填 string(32)

【批次名称】该笔商家转账的名称

batch_remark 　必填 string(32)

【批次备注】转账说明，UTF8编码，最多允许32个字符

close_reason 　选填 string

【批次关闭原因】如果批次状态为“CLOSED”（已关闭），则有关闭原因。

可选取值

MERCHANT_REVOCATION: 商户主动撤销（页面方式）
OVERDUE_CLOSE: 系统超时关闭，可能原因账户余额不足或其他错误

total_amount 　必填 integer

【转账总金额】转账金额单位为“分”

total_num 　必填 integer

【转账总笔数】一个转账批次单最多发起1000笔转账

create_time 　必填 string(32)

【批次创建时间】批次创建时间
使用rfc3339所定义的格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC8小时，即北京时间）。例如：2023-02-23T13:29:35+08:00表示，北京时间2023年2月23日 13点29分35秒

success_amount 　必填 integer

【转账成功金额】转账成功的金额，单位为“分”。当批次状态为“PROCESSING”（转账中）时，转账成功金额随时可能变化

success_num 　必填 integer

【转账成功笔数】转账成功的笔数。当批次状态为“PROCESSING”（转账中）时，转账成功笔数随时可能变化

failed_amount 　必填 integer

【转账失败金额】转账失败的金额，单位为“分”

failed_num 　必填 integer

【转账失败笔数】转账失败的笔数

transfer_scene_id 　必填 string(36)

【转账场景ID】指定的转账场景ID

data 　选填 array[object]

【转账明细单列表】当批次状态为“FINISHED”（已完成），且成功查询到转账明细单时返回。包括微信明细单号、明细状态信息

属性

detail_id 　必填 string(64)

【商家转账明细单号】微信商家转账系统内部区分转账批次单下不同转账明细单的唯一标识

out_detail_no 　必填 string(32)

【商家明细单号】商户系统内部区分转账批次单下不同转账明细单的唯一标识

detail_state 　必填 string

【明细状态】商家转账明细单状态

可选取值

INIT: 系统转账校验中
WAIT_PAY: 待二级商户员工（转账验密人）确认, 符合免确认条件时, 系统会自动扭转为转账中
PROCESSING: 正在处理中，转账结果尚未明确
SUCCESS: 转账成功
FAIL: 需要确认失败原因后，再决定是否重新发起对该笔明细单的转账（并非整个转账批次单）
BANK_REFUND: 银行返回转账成功后，拒绝入账，资金会返回商户账户。

offset 　选填 integer

【请求资源起始位置】该次请求资源（转账明细单）的起始位置，从0开始，默认值为0

limit 　选填 integer

【最大资源条数】该次请求可返回的最大资源（转账明细单）条数，最小20条，最大100条，不传则默认20条。不足20条按实际条数返回

应答示例

200 OK

1{
2  "transfer_batch" : {
3    "out_batch_no" : "sjzz20230223",
4    "batch_id" : "131000011085109987515042023022300246500006",
5    "sp_appid" : "wxf636efh567hg4356",
6    "sub_mchid" : "1900000109",
7    "sub_appid" : "wxf636efh567hg4356",
8    "batch_state" : "ACCEPTED",
9    "batch_name" : "2023年2月深圳分部转账单",
10    "batch_remark" : "2023年2月深圳分部报销单",
11    "close_reason" : "OVERDUE_CLOSE",
12    "total_amount" : 4000000,
13    "total_num" : 200,
14    "create_time" : "2023-02-23T13:29:35+08:00",
15    "success_amount" : 3900000,
16    "success_num" : 199,
17    "failed_amount" : 100000,
18    "failed_num" : 1,
19    "transfer_scene_id" : "1000"
20  },
21  "data" : [
22    {
23      "detail_id" : "132000011085109987515042023022300246521006",
24      "out_detail_no" : "x23zy545Bd5436",
25      "detail_state" : "SUCCESS"
26    }
27  ],
28  "offset" : 0,
29  "limit" : 20
30}
31

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服