查询红包记录 - 接口文档 - 企业微信开发者中心

开发者中心

首页

教程

接口

社区

工具

企业内部开发

快速入门服务端API 客户端API 附录更新日志联系我们

企业内部开发服务端API 企业支付企业红包查询红包记录

查询红包记录

最后更新：2019/12/06

API接口协议

注意事项：

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

请求地址：https://api.mch.weixin.qq.com/mmpaymkttransfers/queryworkwxredpack
是否需要证书 : **是
请求方式：POST
数据格式：**xml

请求示例：

<xml>
	<nonce_str>5K8264ILTKCH16CQ2502SI8ZNMTM67VS</nonce_str>
	<sign>C380BEC2BFD727A4B6845133519F3AD6</sign>
	<mch_billno>123456</mch_billno>
	<mch_id>10000098</mch_id>
	<appid>wx8888888888888888</appid>
</xml>

参数说明：

字段名	字段	必填	示例值	类型
随机字符串	nonce_str	是	5K8264ILTKCH16CQ2502SI8ZNMTM67VS	String(32)
微信支付签名	sign	是	C380BEC2BFD727A4B6845133519F3AD6	String(32)
商户订单号	mch_billno	是	123456	String(28)
商户号	mch_id	是	10000098	String(32)
Appid	appid	是	wxe062425f740d30d8	String(32)

返回结果：

<xml>
	<return_code><![CDATA[SUCCESS]]></return_code>
	<return_msg><![CDATA[ok]]></return_msg>
	<sign><![CDATA[C380BEC2BFD727A4B6845133519F3AD6]]></sign>
	<result_code><![CDATA[SUCCESS]]></result_code>
	<mch_billno><![CDATA[123456]]></mch_billno>
	<mch_id><![CDATA[10000098]]></mch_id>
	<detail_id><![CDATA[43235678654322356]]></detail_id>
	<status><![CDATA[RECEIVED]]></status>
	<send_type><![CDATA[API]]></send_type>
	<total_amount><![CDATA[5000]]></total_amount>
	<reason><![CDATA[余额不足]]></reason>
	<send_time><![CDATA[2017-07-20 22：45：12]]></send_time>
	<wishing><![CDATA[新年快乐]]></wishing>
	<remark><![CDATA[新年红包]]></remark>
	<act_name><![CDATA[新年红包]]></act_name>
	<openid><![CDATA[ohO4GtzOAAYMp2yapORH3dQB3W18]]></openid>
	<amount><![CDATA[100]]></amount>
	<rcv_time><![CDATA[2017-07-20 22：46：59]]></rcv_time>
	<sender_name><![CDATA[XX活动]]></sender_name>
	<sender_header_media_id><![CDATA[1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0]]></sender_header_media_id>
</xml>

返回参数:

字段名	字段	必填	示例值	类型	说明
返回状态码	return_code	是	SUCCESS	String(16)	SUCCESS/FAIL此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断
返回信息	return_msg	否	签名失败	String(128)	返回信息，如非空，为错误原因

以下字段在return_code为SUCCESS的时候有返回:

字段名	字段	必填	示例值	类型	说明
微信支付签名	sign	是	C380BEC2BFD727A4B6845133519F3AD6	String(32)	微信支付签名
业务结果	result_code	是	SUCCESS	String(16)	SUCCESS/FAIL
错误代码	err_code	否	SYSTEMERROR	String(32)	错误码信息
错误代码描述	err_code_des	否	系统错误	String(128)	结果信息描述

以下字段在return_code 和result_code都为SUCCESS的时候有返回:

字段名	字段	必填	示例值	类型	说明
商户订单号	mch_billno	是	1E+25	String(28)	商户使用查询API填写的商户单号的原路返回
商户号	mch_id	是	10000098	String(32)	微信支付分配的商户号
红包单号	detail_id	是	1E+27	String(32)	使用API发放现金红包时返回的红包单号
红包状态	status	是	RECEIVED	string(16)	SENDING:发放 SENT:已发放待领取 FAILED：发放失败 RECEIVED:已领取 RFUND_ING:退款中 REFUND:已退款
发放类型	send_type	是	API	String(32)	API:通过API接口发放
红包金额	total_amount	是	5000	int	红包总金额（单位分）
失败原因	reason	否	余额不足	String(32)	发送失败原因
红包发送时间	send_time	是	########	String(32)
红包退款时间	refund_time	否	########	String(32)	红包的退款时间（如果其未领取的退款）
红包退款金额	refund_amount	否	8000	Int	红包退款金额
祝福语	wishing	否	新年快乐	String(128)	祝福语
活动描述	remark	否	新年红包	String(256)	活动描述，低版本微信可见
活动名称	act_name	否	新年红包	String(32)	发红包的活动名称
领取红包的Openid	openid	是	ohO4GtzOAAYMp2yapORH3dQB3W18	String(32)	领取红包的openid
金额	amount	是	100	int	领取金额
接收时间	rcv_time	是	########	String(32)	领取红包的时间
发送者名称	sender_name	是	XX活动	String(128)	发送者名称
发送者头像	sender_header_media_id	否	1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0	String(128)	发送者头像素材，通过企业微信开放接口上传获取

错误码:

错误码	错误描述	解决方式
CA_ERROR	请求未携带证书，或请求携带的证书出错	到商户平台下载证书，请求带上证书后重试。
SIGN_ERROR	微信支付签名错误	按文档要求重新生成签名后再重试。
NO_AUTH	没有权限	请联系微信支付开通api权限
NOT_FOUND	指定单号数据不存在	查询单号对应的数据不存在，请使用正确的商户订单号查询
FREQ_LIMIT	受频率限制	请对请求做频率控制
XML_ERROR	请求的xml格式错误，或者post的数据为空	检查请求串，确认无误后重试
PARAM_ERROR	参数错误	请查看err_code_des，修改设置错误的参数
PSYSTEMERROR	系统繁忙，请再试	红包系统繁忙

发放企业红包

向员工付款

本节内容

查询红包记录