发放企业红包

API接口协议

发放规则：

发送频率限制———默认1800/min

发送个数上限———默认1800/min

场景金额限制———默认红包金额为1-200元，如有需要，可前往商户平台进行设置和申请

其他限制———商户单日出资金额上限—100万元；单用户单日收款金额上限—1000元；单用户可领取红包个数上限—10个

注意事项：

红包金额大于200或者小于1元时，请求参数scene_id必传，参数说明见下文。

根据监管要求，新申请商户号使用现金红包需要满足两个条件：1、入驻时间超过90天 2、连续正常交易30天。

移动应用的appid无法使用红包接口。

当返回错误码为“SYSTEMERROR”时，请不要更换商户订单号，一定要使用原商户订单号重试，否则可能造成重复发放红包等资金风险。

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

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

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

请商户在自身的系统中合理设置发放频次并做好并发控制，防范错付风险。

因商户自身系统设置存在问题导致的资金损失，由商户自行承担。

**是否需要证书：**是
**数据格式：**xml
证书使用详见：https://pay.weixin.qq.com/wiki/doc/api/tools/mch_pay.php?chapter=4_3

以下字段在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)	商户订单号（每个订单号必须唯一）组成：mch_id+yyyymmdd+10位一天内不能重复的数字
商户号	mch_id	是	10000098	String(32)	微信支付分配的商户号
公众账号appid	wxappid	是	wx8888888888888888	String(32)	商户appid，接口传入的所有appid应该为公众号的appid（在mp.weixin.qq.com申请的），不能为APP的appid（在open.weixin.qq.com申请的）
用户openid	re_openid	是	oxTWIuGaIt6gTKsQRLau2M0yL16E	String(32)	接受收红包的用户在wxappid下的openid
付款金额	total_amount	是	1000	int	付款金额，单位分
微信单号	send_listid	是	1E+29	String(32)	红包订单的微信单号
发送者名称	sender_name	是	XX活动	String(128)	红包发送者名称(需要utf-8格式)
发送者头像	sender_header_media_id	是	1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0	String(128)	发送者头像素材id，通过企业微信开放上传素材接口获取

错误码:

错误码	错误描述	原因	解决方式
NO_AUTH	发放失败，此请求可能存在风险，已被微信拦截	用户账号异常，被拦截	请提醒用户检查自身帐号是否异常。使用常用的活跃的微信号可避免这种情况。
SENDNUM_LIMIT	该用户今日领取红包个数超过限制	该用户今日领取红包个数超过你在微信支付商户平台配置的上限	如有需要、请在微信支付商户平台-现金红包-产品设置中重新配置【每日同一用户领取本商户红包不允许超过的个数】。
SENDAMOUNT_LIMIT	您的商户号今日发放金额超过限制，如有需要请登录微信支付商户平台更改API安全配置	商户今日发放的总金额超过您在微信支付商户平台配置的上限	如有需要，请联系管理员在商户平台-现金红包-产品设置上调整单日发送金额上限。
RCVDAMOUNT_LIMIT	该用户今日领取金额超过限制，如有需要请登录微信支付商户平台更改API安全配置	该用户今日领取红包总金额超过您在微信支付商户平台配置的上限	如有需要，请联系管理员在商户平台-现金红包-产品设置上调整单用户单日领取金额上限。
ILLEGAL_APPID	非法appid，请确认是否为公众号的appid，不能为APP的appid	错误传入了app的appid	接口传入的所有appid应该为公众号的appid（在mp.weixin.qq.com申请的），不能为APP的appid（在open.weixin.qq.com申请的）。
MONEY_LIMIT	红包金额发放限制	发送红包金额不在限制范围内	每个红包金额必须在默认额度内（默认大于1元，小于200元，可在产品设置中自行申请调高额度）
SEND_FAILED	红包发放失败,请更换单号再重试	该红包已经发放失败	如果需要重新发放，请更换单号再发放
FATAL_ERROR	openid和原始单参数不一致	更换了openid，但商户单号未更新	请商户检查代码实现逻辑
CA_ERROR	CA证书出错，请登录微信支付商户平台下载证书	请求携带的证书出错	到商户平台下载证书，请求带上证书后重试
SIGN_ERROR	签名错误；企业微信签名失败	1. 没有使用商户平台设置的商户API密钥进行加密（有可能之前设置过密钥，后来被修改了，没有使用新的密钥进行加密）。 2. 加密前没有按照文档进行参数排序（可参考文档）。 3. 把值为空的参数也进行了签名。可到（http://mch.weixin.qq.com/wiki/tools/signverify/ ）验证。 4. 如果以上3步都没有问题，把请求串中(post的数据）里面中文都去掉，换成英文，试下，看看是否是编码问题。（post的数据要求是utf8） 5. 没有按照企业微信签名算法进行签名	1. 到商户平台重新设置新的密钥后重试； 2. 检查请求参数把空格去掉重试； 3. 中文不需要进行encode，使用CDATA； 4. 按文档要求生成签名后再重试； 5. 检查企业微信支付应用secret是否和企业微信管理端支付应用的secret保持一致；检查参与企业微信签名的字段是否和签名算法里面的字段保持一直。
SYSTEMERROR	请求已受理，请稍后使用原单号查询发放结果	系统无返回明确发放结果	使用原单号调用接口，查询发放结果，如果使用新单号调用接口，视为新发放请求
XML_ERROR	输入xml参数格式错误	请求的xml格式错误，或者post的数据为空	检查请求串，确认无误后重试
FREQ_LIMIT	超过频率限制,请稍后再试	受频率限制	请对请求做频率控制（可联系微信支付wxhongbao@tencent.com申请调高）
NOTENOUGH	帐号余额不足，请到商户平台充值后再重试	账户余额不足	充值后重试
OPENID_ERROR	openid和appid不匹配	openid和appid不匹配	发红包的openid必须是本appid下的openid
PROCESSING	请求已受理，请稍后使用原单号查询发放结果	发红包流程正在处理	二十分钟后查询,按照查询结果成功失败进行处理
PARAM_ERROR	请求参数错误	请求携带的字段非法（或者没填）	请检查字段后重试;如果是重试请求，请与原单请求的金额保持一致。
NO_COMPETENCE	商户号错误	该商户号没有开通企业支付	该商户号没有开通企业支付，请登录企业微信管理端，进入企业支付应用核对商户号是否正确
API_METHOD_CLOSED	您的商户号API发放方式已关闭，请联系管理员在商户平台开启。	商户API发放方式处于关闭状态	请联系管理员在微信支付商户平台开启。

文档ID: 11543
原文档地址：
https://open.work.weixin.qq.com/api/doc/90000/90135/90275

请求参数

Body 参数application/xml

nonce_str

string

随机字符串

必需

随机字符串，不长于32位

sign

string

微信支付签名

必需

参见“签名算法”

mch_billno

string

商户订单号

必需

商户订单号（每个订单号必须唯一。取值范围：0~~9，a~~z，A~Z）.接口根据商户订单号支持重入，如出现超时可再调用。组成参考：mch_id+yyyymmdd+10位一天内不能重复的数字

mch_id

string

必需

微信支付分配的商户号

wxappid

string

公众账号appid

必需

微信分配的公众账号ID（企业微信corpid即为此appId）。接口传入的所有appid应该为公众号的appid（在mp.weixin.qq.com申请的），不能为APP的appid（在open.weixin.qq.com申请的）。

sender_name

string

发送者名称

可选

发送者名称

sender_header_media_id

string

发送者头像

可选

发送者头像素材id，通过企业微信开放上传素材接口获取

re_openid

string

必需

接受红包的用户.用户在wxappid下的openid。获取用户openid参见：http://work.weixin.qq.com/api/doc#11279

total_amount

string

必需

金额，单位分，单笔最小金额默认为1元

wishing

string

红包祝福语

必需

act_name

string

项目名称

必需

remark

string

备注信息

必需

workwx_sign

string

企业微信签名

必需

scene_id

string

必需

发放红包使用场景，红包金额大于200或者小于1元时必传 PRODUCT_1:商品促销 PRODUCT_2:抽奖 PRODUCT_3:虚拟物品兑奖 PRODUCT_4:企业内部福利 PRODUCT_5:渠道分润 PRODUCT_6:保险回馈 PRODUCT_7:彩票派奖 PRODUCT_8:税务刮奖

示例

<xml>
    <nonce_str>5K8264ILTKCH16CQ2502SI8ZNMTM67VS</nonce_str>
    <sign>C380BEC2BFD727A4B6845133519F3AD6</sign>
    <mch_billno>123456</mch_billno>
    <mch_id>10000098</mch_id>
    <wxappid>wx8888888888888888</wxappid>
    <sender_name>XX活动</sender_name>
    <sender_header_media_id>1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0</sender_header_media_id>
    <re_openid>oxTWIuGaIt6gTKsQRLau2M0yL16E</re_openid>
    <total_amount>1000</total_amount>
    <wishing>感谢您参加猜灯谜活动，祝您元宵节快乐！</wishing>
    <act_name>猜灯谜抢红包活动</act_name>
    <remark>猜越多得越多，快来抢！</remark>
    <workwx_sign>99BCDAFF065A4B95628E3DB468A874A8</workwx_sign>
</xml>

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

Body

return_code

string

返回状态码

必需

SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断

return_msg

string

可选

返回信息，如非空，为错误原因

sign

string

微信支付签名

必需

result_code

string

业务结果

必需

SUCCESS/FAIL

mch_billno

string

必需

商户订单号（每个订单号必须唯一）组成：mch_id+yyyymmdd+10位一天内不能重复的数字

mch_id

string

必需

微信支付分配的商户号

wxappid

string

必需

商户appid，接口传入的所有appid应该为公众号的appid（在mp.weixin.qq.com申请的），不能为APP的appid（在open.weixin.qq.com申请的

re_openid

string

必需

接受收红包的用户在wxappid下的openid

total_amount

string

付款金额，单位分

必需

send_listid

string

红包订单的微信单号

必需

sender_name

string

必需

红包发送者名称(需要utf-8格式)

sender_header_media_id

string

必需

发送者头像素材id，通过企业微信开放上传素材接口获取

示例

<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>
    <wxappid><![CDATA[wx8888888888888888]]></wxappid>
    <re_openid><![CDATA[oxTWIuGaIt6gTKsQRLau2M0yL16E]]></re_openid>
    <total_amount><![CDATA[1000]]></total_amount>
    <send_listid><![CDATA[235785324578098]]></send_listid>
    <sender_name><![CDATA[XX活动]]></sender_name>
    <sender_header_media_id><![CDATA[1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0]]></sender_header_media_id>
</xml>

API接口协议#

请求参数

示例代码

返回响应

API接口协议