API介绍

简介

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

注意事项

◆ 如果查询单号对应的数据不存在,那么数据不存在的原因可能是:(1)付款还在处理中;(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) 通过签名算法计算得出的签名值,详见签名生成算法

数据示例:

<xml>
<mch_id>2302758702</mch_id>
<nonce_str>50780e0cca98c8c8e814883e5caa672e</nonce_str>
<partner_trade_no>1212121221278</partner_trade_no>
<sign>34bf02fe5b20f117365ef6f5d0436be1</sign>
</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) 代付订单状态:
  1. PROCESSING(处理中,如有明确失败,则返回额外失败原因;否则没有错误原因)
  2. SUCCESS(付款成功)
  3. FAILED(付款失败,需要替换付款单号重新发起付款)
  4. BANK_FAIL(银行退票,订单状态由付款成功流转至退票,退票时付款金额和手续费会自动退还)
手续费金额 cmms_amt int 手续费订单金额 RMB:分
商户下单时间 create_time String(32) 微信侧订单创建时间
成功付款时间 pay_succ_time String(32) 微信侧付款成功时间(依赖银行的处理进度,可能出现延迟返回,甚至被银行退票的情况)
失败原因 reason String(128) 订单失败原因(如:余额不足)

成功示例:

<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[ok]]></return_msg>
<result_code><![CDATA[SUCCESS]]></result_code>
<err_code><![CDATA[SUCCESS]]></err_code>
<err_code_des><![CDATA[ok]]></err_code_des>
<mch_id><![CDATA[2302758702]]></mch_id>
<partner_trade_no><![CDATA[1212121221278]]></partner_trade_no>
<payment_no><![CDATA[10000600500852017030900000020006012]]></payment_no>
<bank_no_md5><![CDATA[2260AB5EF3D290E28EFD3F74FF7A29A0]]></bank_no_md5>
<true_name_md5><![CDATA[7F25B325D37790764ABA55DAD8D09B76]]></true_name_md5>
<amount>500</amount>
<status><![CDATA[处理中]]></status>
<cmms_amt>0</cmms_amt>
<create_time><![CDATA[2017-03-09 15:04:04]]></create_time>
<reason><![CDATA[]]></reason>
</xml>

错误示例:

<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[订单不存在,请核实后再查]]></return_msg>
<result_code><![CDATA[FAIL]]></result_code>
<err_code><![CDATA[ORDERNOTEXIST]]></err_code>
<err_code_des><![CDATA[订单不存在,请核实后再查]]></err_code_des>
</xml>

错误码

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

1、查询单号对应的数据不存在,请使用正确的商户订单号查询

2、如需查询超过有效期的单据,请登录到商户平台进行查询