查询付款银行API

更新时间：2024.11.13

简介

用于对商户付款到银行卡操作进行结果查询，返回付款操作详细结果。

注意事项：

如果查询单号对应的数据不存在，那么数据不存在的原因可能是：（1）付款还在处理中；（2）付款处理失败导致付款订单没有落地。在上述情况下，商户首先需要检查该商户订单号是否确实是自己发起的，如果商户确认是自己发起的，则请商户不要直接当做付款失败处理，请商户隔几分钟再尝试查询（请勿付款和查询并发处理），或者商户可以通过相同的商户订单号再次发起付款（支持2个自然日内的单据，超过2个自然日请确认付款失败后再换单发起）。如果商户误把还在付款处理中的订单直接当付款失败处理，商户应当自行承担因此产生的所有损失和责任。
XML具有可扩展性，因此返回参数可能会有新增，而且顺序可能不完全遵循此文档规范，如果在解析回包的时候发生错误，请商户务必不要换单重试，请商户联系客服确认付款情况。如果有新回包字段，会更新到此API文档中。
因为错误代码字段err_code的值后续可能会增加，所以商户如果遇到回包返回新的错误码，请商户务必不要换单重试，请商户联系客服确认付款情况。如果有新的错误码，会更新到此API文档中。
错误代码描述字段err_code_des和失败原因字段reason只供人工定位问题时做参考，系统实现时不要依赖这个字段来做自动化处理。

接口调用请求说明

请求Url	https://api.mch.weixin.qq.com/mmpaysptrans/query_bank
是否需要证书	是（证书及使用说明详见商户证书）
请求方式	POST
接口调用频率限制	30/s

请求参数

字段名	字段	必填	示例值	类型	说明
商户号	mch_id	是	1900000109	string(32)	微信支付分配的商户号
商户付款单号	partner_trade_no	是	1212121221227	string(32)	商户订单号，需保持唯一（只允许数字[0~9]或字母[A~Z]和[a~z]最短8位，最长32位）
随机字符串	nonce_str	是	5K8264ILTKCH16CQ2502SI8ZNMTM67Vs	string(32)	随机字符串，长度小于32位
签名	sign	是	C380BEC2BFD727A4B6845133519F3AD6	string(32)	通过签名算法计算得出的签名值，详见签名生成算法

数据示例：

1<xml>
2<mch_id>2302758702</mch_id>
3<nonce_str>50780e0cca98c8c8e814883e5caa672e</nonce_str>
4<partner_trade_no>1212121221278</partner_trade_no>
5<sign>34bf02fe5b20f117365ef6f5d0436be1</sign>
6</xml>

返回参数

字段名	变量名	必填	类型	说明
返回状态码	return_code	是	String(16)	SUCCESS/FAIL 此字段是通信标识，非付款标识，付款是否成功需要查看result_code来判断
返回信息	return_msg	否	String(128)	返回信息，如非空，为错误原因签名失败参数格式校验错误
以下字段在return_code为SUCCESS的时候有返回
业务结果	result_code	是	String(16)	SUCCESS/FAIL，非付款标识，付款是否成功需要查看status字段来判断
错误代码	err_code	否	String(32)	错误码信息
错误代码描述	err_code_des	否	String(128)	结果信息描述
以下字段在return_code 和result_code都为SUCCESS的时候有返回
商户号	mch_id	是	string(32)	商户号
商户付款单号	partner_trade_no	是	string(32)	商户单号
微信付款单号	payment_no	是	string(64)	即为微信内部业务单号
银行卡号	bank_no_md5	是	string(32)	收款用户银行卡号(MD5加密)
用户真实姓名	true_name_md5	是	string(32)	收款人真实姓名（MD5加密）
代付金额	amount	是	int	代付订单金额RMB：分
代付单状态	status	是	string(16)	代付订单状态： PROCESSING（处理中，如有明确失败，则返回额外失败原因；否则没有错误原因） SUCCESS（付款成功） FAILED（付款失败,需要替换付款单号重新发起付款） BANK_FAIL（银行退票，订单状态由付款成功流转至退票,退票时付款金额和手续费会自动退还）
手续费金额	cmms_amt	是	int	手续费订单金额 RMB：分
商户下单时间	create_time	是	String(32)	微信侧订单创建时间
成功付款时间	pay_succ_time	否	String(32)	微信侧付款成功时间（依赖银行的处理进度，可能出现延迟返回，甚至被银行退票的情况）
失败原因	reason	否	String(128)	订单失败原因（如：余额不足）

成功示例：

1<xml>
2<return_code><![CDATA[SUCCESS]]></return_code>
3<return_msg><![CDATA[ok]]></return_msg>
4<result_code><![CDATA[SUCCESS]]></result_code>
5<err_code><![CDATA[SUCCESS]]></err_code>
6<err_code_des><![CDATA[ok]]></err_code_des>
7<mch_id><![CDATA[2302758702]]></mch_id>
8<partner_trade_no><![CDATA[1212121221278]]></partner_trade_no>
9<payment_no><![CDATA[10000600500852017030900000020006012]]></payment_no>
10<bank_no_md5><![CDATA[2260AB5EF3D290E28EFD3F74FF7A29A0]]></bank_no_md5>
11<true_name_md5><![CDATA[7F25B325D37790764ABA55DAD8D09B76]]></true_name_md5>
12<amount>500</amount>
13<status><![CDATA[处理中]]></status>
14<cmms_amt>0</cmms_amt>
15<create_time><![CDATA[2017-03-09 15:04:04]]></create_time>
16<reason><![CDATA[]]></reason>
17</xml>

错误示例：

1<xml>
2<return_code><![CDATA[SUCCESS]]></return_code>
3<return_msg><![CDATA[订单不存在，请核实后再查]]></return_msg>
4<result_code><![CDATA[FAIL]]></result_code>
5<err_code><![CDATA[ORDERNOTEXIST]]></err_code>
6<err_code_des><![CDATA[订单不存在，请核实后再查]]></err_code_des>
7</xml>

错误码

错误代码	描述	解决方案
INVALID_REQUEST	无效的请求，商户系统异常导致，商户权限异常、证书错误、频率限制等	使用原单号以及原请求参数重试
PARAM_ERROR	参数错误	按照err_msg指定参数错误信息，修改相应参数
SIGNERROR	签名错误	签名前没有按照要求进行排序。没有使用商户平台设置的密钥进行签名，参数有空格或者进行了encode后进行签名
ORDERNOTEXIST	订单不存在	确认订单号是否发起过请求
SYSTEMERROR	系统繁忙，请稍后重试	使用原单号以及原请求参数重试
SUCCESS	Wx侧查询成功	-
NOT_FOUND	1、指定单号数据不存在 2、指定单号数据不存在，单据查询超过有效期	1、查询单号对应的数据不存在，请使用正确的商户订单号查询 2、如需查询超过有效期的单据，请登录到商户平台进行查询

文档是否有帮助

更多支持

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