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

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_str5K8264ILTKCH16CQ2502SI8ZNMTM67VSString(32)
微信支付签名signC380BEC2BFD727A4B6845133519F3AD6String(32)
商户订单号mch_billno123456String(28)
商户号mch_id10000098String(32)
Appidappidwxe062425f740d30d8String(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 224512]]></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 224659]]></rcv_time>
	<sender_name><![CDATA[XX活动]]></sender_name>
	<sender_header_media_id><![CDATA[1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0]]></sender_header_media_id>
</xml>

返回参数:

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

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

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

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

字段名字段必填示例值类型说明
商户订单号mch_billno1E+25String(28)商户使用查询API填写的商户单号的原路返回
商户号mch_id10000098String(32)微信支付分配的商户号
红包单号detail_id1E+27String(32)使用API发放现金红包时返回的红包单号
红包状态statusRECEIVEDstring(16)SENDING:发放 SENT:已发放待领取 FAILED:发放失败 RECEIVED:已领取 RFUND_ING:退款中 REFUND:已退款
发放类型send_typeAPIString(32)API:通过API接口发放
红包金额total_amount5000int红包总金额(单位分)
失败原因reason余额不足String(32)发送失败原因
红包发送时间send_time########String(32) 
红包退款时间refund_time########String(32)红包的退款时间(如果其未领取的退款)
红包退款金额refund_amount8000Int红包退款金额
祝福语wishing新年快乐String(128)祝福语
活动描述remark新年红包String(256)活动描述,低版本微信可见
活动名称act_name新年红包String(32)发红包的活动名称
领取红包的OpenidopenidohO4GtzOAAYMp2yapORH3dQB3W18String(32)领取红包的openid
金额amount100int领取金额
接收时间rcv_time########String(32)领取红包的时间
发送者名称sender_nameXX活动String(128)发送者名称
发送者头像sender_header_media_id1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0String(128)发送者头像素材,通过企业微信开放接口上传获取

错误码:

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