微信支付批次单号查询批次单
更新时间:2024.11.05服务商可以通过该接口查询转账批次单以及指定状态的转账明细单。
|
接口说明
支持商户:【普通服务商】
请求方式:【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 选填 int
【请求资源起始位置】 该次请求资源的起始位置。返回的明细是按照设置的明细条数进行分页展示的,一次查询可能无法返回所有明细,我们使用该参数标识查询开始位置,默认值为0
limit 选填 int
【最大资源条数】 该次请求可返回的最大明细条数,最小20条,最大100条,不传则默认20条。不足20条按实际条数返回
detail_status 选填 string(32)
【明细状态】 查询指定状态的转账明细单
枚举值:
ALL:全部。需要同时查询转账成功和转账失败的明细单
SUCCESS:转账成功。只查询转账成功的明细单
FAIL:转账失败。只查询转账失败的明细单
请求示例
GET
应答参数
|
sp_mchid 必填 string(32)
【服务商商户号】 微信服务商商户的商户号,由微信支付生成并下发
sub_mchid 必填 string(32)
【特约商户号】微信服务商下特约商户的商户号,由微信支付生成并下发
out_batch_no 必填 string(32)
【商家批次单号】 商户系统内部的商家批次单号,在商户系统内部唯一
batch_id 必填 string(64)
【微信支付批次单号】 微信支付批次单号,微信商家转账系统返回的唯一标识
sub_appid 选填 string(32)
【特约商户appid】 是特约商户在微信申请公众号/小程序或移动应用成功后分配的账号ID(与特约商户主体一致),登录平台为mp.weixin.qq.com
或open.weixin.qq.com
。
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对应的openidINFORMATION_AND_FUND_AUTHORIZATION_TYPE
: 表示使用特约商户的用户信息且出款方为特约商户
batch_name 必填 string(32)
【批次名称】 该笔批量转账的名称
batch_remark 必填 string(32)
【批次备注】 转账说明,UTF8编码,最多允许32个字符
close_reason 选填 string
【批次关闭原因】 如果批次单状态为“CLOSED”(已关闭),则有关闭原因
可选取值
MERCHANT_REVOCATION
: 商户主动撤销(页面方式)OVERDUE_CLOSE
: 系统超时关闭,可能原因账户余额不足或其他错误
total_amount 必填 int
【转账总金额】 转账金额单位为“分”
total_num 必填 int
【转账总笔数】 一个转账批次单最多发起三千笔转账
create_time 选填 string(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秒
update_time 选填 string(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秒
success_amount 选填 int
【转账成功金额】 转账成功的金额,单位为“分”。当批次状态为“PROCESSING”(转账中)时,转账成功金额随时可能变化
success_num 选填 int
【转账成功笔数】 转账成功的笔数。当批次状态为“PROCESSING”(转账中)时,转账成功笔数随时可能变化
fail_amount 选填 int
【转账失败金额】 转账失败的金额,单位为“分”
fail_num 选填 int
【转账失败笔数】 转账失败的笔数
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
错误码
公共错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
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 | 频率超限 | 请求量不要超过接口调用频率限制 |