基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
微信支付分(公共API)
微信支付分(免确认预授权模式)
微信支付分(需确认模式)
支付即服务
行业方案
智慧商圈
微信支付分停车服务
电子发票
营销工具
代金券
商家券
委托营销
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
商家转账到零钱
分账
风险合规
消费者投诉2.0
其他能力
清关报关
图片上传
视频上传
微信支付平台证书

微信批次单号查询批次单API

最新更新时间: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

{
JAVA示例代码
}

返回参数

参数名 变量 类型[长度限制] 必填 描述
+转账批次单 transfer_batch object 转账批次单基本信息
参数名 变量类型[长度限制] 必填 描述
商户号 mchid string[1,32] 微信支付分配的商户号
示例值:1900001109
商家批次单号 out_batch_no string[1,32] 商户系统内部的商家批次单号,在商户系统内部唯一
示例值:plfk2020042013
微信批次单号 batch_id string[1,64] 微信批次单号,微信商家转账系统返回的唯一标识
示例值:1030000071100999991182020050700019480001
直连商户的appid appid string[1,32] 申请商户号的appid或商户号绑定的appid(企业号corpid即为此appid)
示例值:wxf636efh567hg4356
批次状态 batch_status string[1,32] 枚举值:
WAIT_PAY:待付款,商户员工确认付款阶段
ACCEPTED:已受理。批次已受理成功,若发起批量转账的30分钟后,转账批次单仍处于该状态,可能原因是商户账户余额不足等。商户可查询账户资金流水,若该笔转账批次单的扣款已经发生,则表示批次已经进入转账中,请再次查单确认
PROCESSING:转账中。已开始处理批次内的转账明细单
FINISHED:已完成。批次内的所有转账明细单都已处理完成
CLOSED:已关闭。可查询具体的批次关闭原因确认
示例值:ACCEPTED
批次类型 batch_type string[1,32] 枚举值:
API:API方式发起
WEB:页面方式发起
示例值:API
批次名称 batch_name string[1,32] 该笔批量转账的名称
示例值:2019年1月深圳分部报销单
批次备注 batch_remark string[1,32] 转账说明,UTF8编码,最多允许32个字符
示例值:2019年1月深圳分部报销单
批次关闭原因 close_reason string[1,64] 如果批次单状态为“CLOSED”(已关闭),则有关闭原因
MERCHANT_REVOCATION:商户主动撤销
OVERDUE_CLOSE:系统超时关闭
示例值:OVERDUE_CLOSE
转账总金额 total_amount int 转账金额单位为分
示例值:4000000
转账总笔数 total_num int 一个转账批次单最多发起三千笔转账
示例值:200
批次创建时间 create_time string[1,32] 批次受理成功时返回,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss.sss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示北京时间2015年05月20日13点29分35秒
示例值:2015-05-20T13:29:35.120+08:00
批次更新时间 update_time string[1,32] 批次最近一次状态变更的时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss.sss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示北京时间2015年05月20日13点29分35秒
示例值:2015-05-20T13:29:35.120+08:00
转账成功金额 success_amount int 转账成功的金额,单位为分。当批次状态为“PROCESSING”(转账中)时,转账成功金额随时可能变化
示例值:3900000
转账成功笔数 success_num int 转账成功的笔数。当批次状态为“PROCESSING”(转账中)时,转账成功笔数随时可能变化
示例值:199
转账失败金额 fail_amount int 转账失败的金额,单位为分
示例值:100000
转账失败笔数 fail_num int 转账失败的笔数
示例值:1
+转账明细单列表 transfer_detail_list array 当批次状态为“FINISHED”(已完成),且成功查询到转账明细单时返回。包括微信明细单号、明细状态信息
参数名 变量类型[长度限制] 必填 描述
微信明细单号 detail_id string[1,64] 微信支付系统内部区分转账批次单下不同转账明细单的唯一标识
示例值:1040000071100999991182020050700019500100
商家明细单号 out_detail_no string[1,32] 商户系统内部区分转账批次单下不同转账明细单的唯一标识
示例值:x23zy545Bd5436
明细状态 detail_status string[1,32] 枚举值:
PROCESSING:转账中。正在处理中,转账结果尚未明确
SUCCESS:转账成功
FAIL:转账失败。需要通过查询明细单接口确认明细失败原因后,再决定是否重新发起对该笔明细单的转账(并非整个转账批次单)
示例值:SUCCESS

返回示例


{
  "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"
    }
  ]
}
                    

http://2323weixin.qq.com
                    

错误码公共错误码

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


技术咨询

文档反馈