---
url: "https://pay.weixin.qq.com/doc/v2/merchant/4011937431.md"
title: "查询红包记录"
doc_id: 4011937431
---

>更新时间：2025.06.20

## 使用说明

用于商户对已发放的红包进行查询红包的具体信息，可支持普通红包和裂变包。

注意事项：

- 查询红包记录API只支持查询30天内的红包订单，30天之前的红包订单请登录商户平台查询。

- 如果查询单号对应的数据不存在，那么数据不存在的原因可能是：（1）发放请求还在处理中；（2）红包发放处理失败导致红包订单没有落地。在上述情况下，商户首先需要检查该商户订单号是否确实是自己发起的，如果商户确认是自己发起的，则请商户不要直接当做红包发放失败处理，请商户隔几分钟再尝试查询，或者商户可以通过相同的商户订单号再次发起发放请求。如果商户误把还在发放中的订单直接当发放失败处理，商户应当自行承担因此产生的所有损失和责任。

- XML具有可扩展性，因此返回参数可能会有新增，而且顺序可能不完全遵循此文档规范，如果在解析回包的时候发生错误，请商户务必不要换单重试，请商户联系客服确认红包发放情况。如果有新回包字段，会更新到此API文档中。

- 因为错误代码字段err\_code的值后续可能会增加，所以商户如果遇到回包返回新的错误码，请商户务必不要换单重试，请商户联系客服确认红包发放情况。如果有新的错误码，会更新到此API文档中。

- 错误代码描述字段err\_code\_des只供人工定位问题时做参考，系统实现时请不要依赖这个字段来做自动化处理。


## 接口调用请求说明

| 请求Url | https://api.mch.weixin.qq.com/mmpaymkttransfers/gethbinfo |
| --- | --- |
| 是否需要证书 | 是（证书及使用说明详见[商户证书](https://pay.weixin.qq.com/doc/v2/merchant/4011985891.md)） |
| 请求方式 | POST |

## 请求参数

| 字段名 | 字段 | 必填 | 示例值 | 类型 | 说明 |
| --- | --- | --- | --- | --- | --- |
| 随机字符串 | nonce\_str | 是 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | String(32) | 随机字符串，不长于32位 |
| 签名 | sign | 是 | C380BEC2BFD727A4B6845133519F3AD6 | String(32) | 详见[签名生成算法](https://pay.weixin.qq.com/doc/v2/merchant/4011985891.md) |
| 商户订单号 | mch\_billno | 是 | 10000098201411111234567890 | String(28) | 商户发放红包的商户订单号 |
| 商户号 | mch\_id | 是 | 10000098 | String(32) | 微信支付分配的商户号 |
| Appid | appid | 是 | wxe062425f740d30d8 | String(32) | 微信分配的公众账号ID（企业号corpid即为此appId），接口传入的所有appid应该为公众号的appid（在mp.weixin.qq.com申请的），不能为APP的appid（在open.weixin.qq.com申请的）。 |
| 订单类型 | bill\_type | 是 | MCHT | String(32) | MCHT:通过商户订单号获取红包信息。 |

数据示例：

```
<xml>
<sign><![CDATA[E1EE61A91C8E90F299DE6AE075D60A2D]]></sign>
<mch_billno><![CDATA[0010010404201411170000046545]]></mch_billno>
<mch_id><![CDATA[10000097]]></mch_id>
<appid><![CDATA[wxe062425f740c30d8]]></appid>
<bill_type><![CDATA[MCHT]]></ bill_type>
<nonce_str><![CDATA[50780e0cca98c8c8e814883e5caa672e]]></nonce_str>
</xml>
```

## 返回参数

| 字段名 | 变量名 | 必填 | 示例值 | 类型 | 说明 |
| --- | --- | --- | --- | --- | --- |
| 返回状态码 | return\_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL<br>此字段是通信标识，非红包发放结果标识，红包发放是否成功需要结合result\_code以及status来判断 |
| 返回信息 | return\_msg | 否 | 签名失败 | String(128) | 返回信息，如非空，为错误原因<br>签名失败<br>参数格式校验错误 |

以下字段在return\_code为SUCCESS的时候有返回

| 字段名 | 变量名 | 必填 | 示例值 | 类型 | 说明 |
| --- | --- | --- | --- | --- | --- |
| 业务结果 | result\_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL<br>非红包发放结果标识，红包发放是否成功需要查看status字段来判断 |
| 错误代码 | err\_code | 否 | SYSTEMERROR | String(32) | 错误码信息 |
| 错误代码描述 | err\_code\_des | 否 | 系统错误 | String(128) | 结果信息描述 |

以下字段在return\_code 和result\_code都为SUCCESS的时候有返回

| 字段名 | 变量名 | 必填 | 示例值 | 类型 | 描述 |
| --- | --- | --- | --- | --- | --- |
| 商户订单号 | mch\_billno | 是 | 10000098201411111234567890 | String(28) | 商户使用查询API填写的商户单号的原路返回 |
| 商户号 | mch\_id | 是 | 10000098 | String(32) | 微信支付分配的商户号 |
| 红包单号 | detail\_id | 是 | 1000000000201503283103439304 | String(32) | 使用API发放现金红包时返回的红包单号 |
| 红包状态 | status | 是 | RECEIVED | string(16) | SENDING:发放中<br>SENT:已发放待领取<br>FAILED：发放失败<br>RECEIVED:已领取<br>RFUND\_ING:退款中<br>REFUND:已退款 |
| 发放类型 | send\_type | 是 | API | String(32) | API:通过API接口发放<br>UPLOAD:通过上传文件方式发放<br>ACTIVITY:通过活动方式发放 |
| 红包类型 | hb\_type | 是 | GROUP | String(32) | GROUP:裂变红包<br>NORMAL:普通红包 |
| 红包个数 | total\_num | 是 | 1 | int | 红包个数 |
| 红包金额 | total\_amount | 是 | 5000 | int | 红包总金额（单位分） |
| 失败原因 | reason | 否 | 余额不足 | String(32) | 发送失败原因 |
| 红包发送时间 | send\_time | 是 | 2015-04-21 20:00:00 | String(32) | 红包的发送时间 |
| 红包退款时间 | refund\_time | 否 | 2015-04-21 23:03:00 | String(32) | 红包的退款时间（如果其未领取的退款） |
| 红包退款金额 | refund\_amount | 否 | 8000 | int | 红包退款金额 |
| 祝福语 | wishing | 否 | 新年快乐 | String(128) | 祝福语 |
| 活动描述 | remark | 否 | 新年红包 | String(256) | 活动描述，低版本微信可见 |
| 活动名称 | act\_name | 否 | 新年红包 | String(32) | 发红包的活动名称 |
| 裂变红包领取列表 | hblist | 否 | 内容如下表 | array | 裂变红包的领取列表 |
| 领取红包的Openid | openid | 是 | ohO4GtzOAAYMp2yapORH3dQB3W18 | String(32) | 领取红包的openid |
| 金额 | amount | 是 | 100 | int | 领取金额 |
| 接收时间 | rcv\_time | 是 | 2015-04-21 20:00:00 | String(32) | 领取红包的时间 |

成功示例：

```
<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_billno><![CDATA[9010080799701411170000046603]]></mch_billno>
<mch_id><![CDATA[11475856]]></mch_id>
<detail_id><![CDATA[10000417012016080830956240040]]></detail_id>
<status><![CDATA[RECEIVED]]></status>
<send_type><![CDATA[ACTIVITY]]></send_type>
<hb_type><![CDATA[NORMAL]]></hb_type>
<total_num>1</total_num>
<total_amount>100</total_amount>
<send_time><![CDATA[2016-08-08 21:49:22]]></send_time>
<hblist>
<hbinfo>
<openid><![CDATA[oHkLxtzmyHXX6FW_cAWo_orTSRXs]]></openid>
<amount>100</amount>
<rcv_time><![CDATA[2016-08-08 21:49:46]]></rcv_time>
</hbinfo>
</hblist>
</xml>
```

失败示例：

```
<xml>
<return_code><![CDATA[FAIL]]></return_code>
<return_msg><![CDATA[指定单号数据不存在]]></return_msg>
<result_code><![CDATA[FAIL]]></result_code>
<err_code><![CDATA[SYSTEMERROR]]></err_code>
<err_code_des><![CDATA[指定单号数据不存在]]></err_code_des>
<mch_id>666</mch_id>
<mch_billno><![CDATA[1000005901201407261446939688]]></mch_billno>
</xml>
```

## 错误码

| 错误代码 | 描述 | 解决方案 |
| --- | --- | --- |
| CA\_ERROR | 请求未携带证书，或请求携带的证书出错 | 到商户平台下载证书，请求带上证书后重试。 |
| SIGN\_ERROR | 商户签名错误 | 按文档要求重新生成签名后再重试。 |
| NO\_AUTH | 没有权限 | 请联系微信支付开通api权限 |
| NOT\_FOUND | 指定单号数据不存在 | 查询单号对应的数据不存在，请使用正确的商户订单号查询 |
| FREQ\_LIMIT | 受频率限制 | 请对请求做频率控制 |
| XML\_ERROR | 请求的xml格式错误，或者post的数据为空 | 检查请求串，确认无误后重试 |
| PARAM\_ERROR | 参数错误 | 请查看err\_code\_des，修改设置错误的参数 |
| SYSTEMERROR | 系统繁忙，请再试。 | 红包系统繁忙。 |