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

更新时间：2024.11.18

微信支付批次单号查单接口。转账处理后延迟一段时间（异步进行转账），服务商可以通过该接口查询转账批次单以及指定状态的转账明细单。返回消息中包含微信支付批次单号、批次状态、批次类型、转账总金额、转账总笔数、成功金额、失败金额等信息。

接口限频：
单个服务商（查询转账批次单）50QPS，如果超过频率限制，会报错FREQUENCY_LIMITED，请降低频率请求。

注意事项：

API只支持查询最近30天内的转账批次单，30天之前的转账批次单请登录商户平台查询。
转账明细单只会在批次单完成的情况下返回，如果需要在批次处理过程中查询转账明细单，请通过转账明细单查询接口来查询。
转账批次单和明细单中涉及金额的字段单位为“分”。
如果查询单号对应的数据不存在，那么数据不存在的原因可能是：（1）批次还在受理中；（2）批次受理失败导致转账批次单没有落地。在上述情况下，服务商首先需要检查该微信支付批次单号是否确实是自己发起的，如果服务商确认是自己发起的，则请服务商不要直接当做受理失败处理，请服务商隔几分钟再尝试查询（请勿转账和查询并发处理），或者服务商可以通过相同的商家批次单号再次发起转账。如果服务商误把还在受理中的批次单直接当受理失败处理，服务商应当自行承担因此产生的所有损失和责任。
如果遇到回包返回新的错误码，请务必不要换单重试，请联系客服确认转账情况。如果有新的错误码，会更新到此API文档中。
错误码描述字段message只供人工定位问题时做参考，系统实现时请不要依赖这个字段来做自动化处理。

接口说明

支持商户：【普通服务商】

请求方式：【GET】/v3/partner-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 查询参数

need_query_detail 　必填 boolean

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

offset 　选填 integer

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

limit 　选填 integer

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

detail_status 　选填 string(32)

【明细状态】查询指定状态的转账明细单
ALL:全部。同时查询转账成功、失败和待确认的明细单
FAIL:转账失败。只查询转账失败的明细单
SUCCESS:转账成功。只查询转账成功的明细单
WAIT_PAY: 待确认。只查询待出资商户员工（转账验密人）确认的明细单

请求示例

GET

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

应答参数

200 OK

sp_mchid 　必填 string(32)

【服务商商户号】微信支付分配的服务商商户号

sub_mchid 　必填 string(32)

【特约商户号】微信支付分配的特约商户号

out_batch_no 　必填 string(32)

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

batch_id 　必填 string(64)

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

sub_appid 　选填 string(32)

【特约商户appid】微信分配的特约商户公众账号ID。特约商户appid

batch_status 　必填 string(32)

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

batch_type 　必填 string(32)

【批次类型】API:API方式发起
WEB:页面方式发起

authorization_type 　必填 string

【特约商户授权类型】特约商户授权类型

可选取值：

INFORMATION_AUTHORIZATION_TYPE: 表示使用特约商户用户信息，出款方服务商

FUND_AUTHORIZATION_TYPE: 表示使用特约商户的资金，出款方为特约商户，用户信息为服务商appid对应的openid

INFORMATION_AND_FUND_AUTHORIZATION_TYPE: 表示使用特约商户的用户信息且出款方为特约商户

batch_name 　必填 string(32)

【批次名称】该笔批量转账的名称

batch_remark 　必填 string(32)

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

close_reason 　选填 string

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

可选取值：

MERCHANT_REVOCATION: 商户主动撤销（页面方式）

OVERDUE_CLOSE: 系统超时关闭，可能原因账户余额不足或其他错误

total_amount 　必填 integer

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

total_num 　必填 integer

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

create_time 　选填 string(32)

【批次创建时间】批次受理成功时返回，按照使用rfc3339所定义的格式，格式为YYYY-MM-DDThh:mm:ss+TIMEZONE

update_time 　选填 string(32)

【批次更新时间】批次最近一次状态变更的时间，按照使用rfc3339所定义的格式，格式为YYYY-MM-DDThh:mm:ss+TIMEZONE

success_amount 　选填 integer

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

success_num 　选填 integer

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

fail_amount 　选填 integer

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

fail_num 　选填 integer

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

transfer_detail_list 　选填 array[object]

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

属性

sp_appid 　选填 string(32)

【服务商的appid】微信分配的服务商商户公众账号ID，特约商户授权类型为FUND_AUTHORIZATION_TYPE时才有该字段

transfer_purpose 　选填 string

【批量转账用途】批量转账用途

可选取值：

GOODSPAYMENT: 给用户支付货物采购资金

COMMISSION: 给用户支付业务推广佣金

REFUND: 给用户支付交易退款

REIMBURSEMENT: 企业给员工支付差旅等报销资金

FREIGHT: 给司机支付运输费用

OTHERS: 其他

transfer_scene 　选填 string

【转账场景】商户的转账场景

可选取值：

ORDINARY_TRANSFER: 普通转账（默认）

PAYROLL_CARD_TRANSFER: 给使用微信务工卡的用户进行转账

应答示例

200 OK

1{
2  "sp_mchid" : "1900001109",
3  "sub_mchid" : "1900000109",
4  "out_batch_no" : "plfk2020042013",
5  "batch_id" : "1030000071100999991182020050700019480001",
6  "sub_appid" : "wxf636efh567hg4356",
7  "batch_status" : "ACCEPTED",
8  "batch_type" : "API",
9  "authorization_type" : "INFORMATION_AUTHORIZATION_TYPE",
10  "batch_name" : "2019年1月深圳分部报销单",
11  "batch_remark" : "2019年1月深圳分部报销单",
12  "close_reason" : "MERCHANT_REVOCATION",
13  "total_amount" : 4000000,
14  "total_num" : 200,
15  "create_time" : "2015-05-20T13:29:35.120+08:00",
16  "update_time" : "2015-05-20T13:29:35.120+08:00",
17  "success_amount" : 3900000,
18  "success_num" : 199,
19  "fail_amount" : 100000,
20  "fail_num" : 1,
21  "transfer_detail_list" : [
22    {
23      "detail_id" : "1040000071100999991182020050700019500100",
24      "out_detail_no" : "x23zy545Bd5436",
25      "detail_status" : "SUCCESS"
26    }
27  ],
28  "sp_appid" : "wxf636efh567hg4388",
29  "transfer_purpose" : "GOODSPAYMENT",
30  "transfer_scene" : "ORDINARY_TRANSFER"
31}
32

错误码

公共错误码

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

业务错误码

状态码	错误码	描述	解决方案
500	SYSTEM_ERROR	系统错误	5开头的状态码都为系统问题，请使用相同参数稍后重新调用
400	INVALID_REQUEST	请求参数符合参数格式，但不符合业务规则	查询单据超过限定时间(30天)，可以尝试通过商户平台预约下载
404	NOT_FOUND	记录不存在	查询的转账批次单不存在
429	FREQUENCY_LIMITED	频率超限	请求量不要超过接口调用频率限制

文档是否有帮助

更多支持

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