发放裂变红包

发放规则

裂变红包:一次可以发放一组红包。首先领取的用户为种子用户,种子用户领取一组红包当中的一个,并可以通过社交分享将剩下的红包给其他用户。裂变红包充分利用了人际传播的优势。

 注意事项:
◆ 当返回错误码为“SYSTEMERROR”时,请不要更换商户订单号,一定要使用原商户订单号重试,否则可能造成重复发放红包等资金风险。
◆ XML具有可扩展性,因此返回参数可能会有新增,而且顺序可能不完全遵循此文档规范,如果在解析回包的时候发生错误,请商户务必不要换单重试,请商户联系客服确认红包发放情况。如果有新回包字段,会更新到此API文档中。
◆ 因为错误代码字段err_code的值后续可能会增加,所以商户如果遇到回包返回新的错误码,请商户务必不要换单重试,请商户联系客服确认红包发放情况。如果有新的错误码,会更新到此API文档中。
◆ 错误代码描述字段err_code_des只供人工定位问题时做参考,系统实现时请不要依赖这个字段来做自动化处理。

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

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

 

消息触达规则

现金红包发放后会以公众号消息的形式触达用户,不同情况下触达消息的形式会有差别,规则如下:

是否关注 关注时间 是否接收消息 触达消息
/ / 模板消息
<=50小时 模板消息
<=50小时 模板消息
>50小时 防伪消息
>50小时 模板消息

接口调用请求说明

请求Url https://api.mch.weixin.qq.com/mmpaymkttransfers/sendgroupredpack
是否需要证书 是(证书及使用说明详见商户证书
请求方式 POST

请求参数

字段名 字段 必填 示例值 类型 说明
随机字符串 nonce_str 5K8264ILTKCH16CQ2502SI8ZNMTM67VS String(32) 随机字符串,不长于32位
签名 sign C380BEC2BFD727A4B6845133519F3AD6 String(32) 详见签名生成算法
商户订单号 mch_billno 10000098201411111234567890 String(28)

商户订单号(每个订单号必须唯一

组成:mch_id+yyyymmdd+10位一天内不能重复的数字。

接口根据商户订单号支持重入,如出现超时可再调用。

商户号 mch_id 10000098 String(32) 微信支付分配的商户号
子商户号 sub_mch_id 10000090 String(32) 微信支付分配的子商户号,服务商模式下必填
公众账号appid wxappid wx8888888888888888 String(32) 微信分配的公众账号ID(企业号corpid即为此appId),接口传入的所有appid应该为公众号的appid(在mp.weixin.qq.com申请的),不能为APP的appid(在open.weixin.qq.com申请的)。
触达用户appid msgappid wx28b16568a629bb33 String(32) 服务商模式下触达用户时的appid(可填服务商自己的appid或子商户的appid),服务商模式下必填,服务商模式下填入的子商户appid必须在微信支付商户平台中先录入,否则会校验不过。
商户名称 send_name 天虹百货 String(32)

红包发送者名称

用户openid re_openid oxTWIuGaIt6gTKsQRLau2M0yL16E String(32)

接收红包的种子用户(首个用户)

用户在wxappid下的openid

付款金额 total_amount 1000 int 红包发放总金额,即一组红包金额总和,包括分享者的红包和裂变的红包,单位分
红包发放总人数 total_num 3 int 红包发放总人数,即总共有多少人可以领到该组红包(包括分享者)
红包金额设置方式 amt_type ALL_RAND String(32)

红包金额设置方式

ALL_RAND—全部随机,商户指定总金额和红包发放总人数,由微信支付随机计算出各红包金额

红包祝福语 wishing 感谢您参加猜灯谜活动,祝您元宵节快乐! String(128)

红包祝福语

活动名称 act_name 猜灯谜抢红包活动 String(32)

活动名称

备注 remark 猜越多得越多,快来抢! String(256) 备注信息
场景id scene_id PRODUCT_8 String(32)

PRODUCT_1:商品促销

PRODUCT_2:抽奖

PRODUCT_3:虚拟物品兑奖 

PRODUCT_4:企业内部福利

PRODUCT_5:渠道分润

PRODUCT_6:保险回馈

PRODUCT_7:彩票派奖

PRODUCT_8:税务刮奖

活动信息 risk_info posttime%3d123123412%26clientversion%3d234134%26mobile%3d122344545%26deviceid%3dIOS String(128)

posttime:用户操作的时间戳

mobile:业务系统账号的手机号,国家代码-手机号。不需要+号

deviceid :mac 地址或者设备唯一标识 

clientversion :用户操作的客户端版本

把值为非空的信息用key=value进行拼接,再进行urlencode

urlencode(posttime=xx& mobile =xx&deviceid=xx)

数据示例:

<xml> 

   <sign><![CDATA[E1EE61A91C8E90F299DE6AE075D60A2D]]></sign>

   <mch_billno><![CDATA[0010010404201411170000046545]]></mch_billno>

   <mch_id><![CDATA[1000888888]]></mch_id>

   <sub_mch_id><![CDATA[1000888888]]></sub_mch_id>

   <wxappid><![CDATA[wxcbda96de0b165486]]></wxappid> 

   <send_name><![CDATA[send_name]]></send_name> 

   <re_openid><![CDATA[onqOjjmM1tad-3ROpncN-yUfa6uI]]></re_openid> 

   <total_amount><![CDATA[600]]></total_amount> 

   <amt_type><![CDATA[ALL_RAND]]></amt_type> 

   <total_num><![CDATA[3]]></total_num> 

   <wishing><![CDATA[恭喜发财]]></wishing>

   <act_name><![CDATA[新年红包]]></act_name> 

   <remark><![CDATA[新年红包]]></remark> 

   <scene_id><![CDATA[PRODUCT_2]]></scene_id>

   <nonce_str><![CDATA[50780e0cca98c8c8e814883e5caa672e]]></nonce_str> 

   <risk_info>posttime%3d123123412%26clientversion%3d234134%26mobile%3d122344545%26deviceid%3dIOS</risk_info>

</xml>

返回参数

字段名 变量名 必填 示例值 类型 说明
返回状态码 return_code SUCCESS String(16)

SUCCESS/FAIL

此字段是通信标识,非红包发放结果标识,红包发放是否成功需要查看result_code来判断

返回信息 return_msg 签名失败 String(128)

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

签名失败

参数格式校验错误

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

字段名 变量名 必填 示例值 类型 说明
业务结果 result_code SUCCESS String(16)

SUCCESS/FAIL

注意:当状态为FAIL时,存在业务结果未明确的情况。所以如果状态是FAIL,请务必再请求一次查询接口[请务必关注错误代码(err_code字段),通过查询得到的红包状态确认此次发放的结果。],以确认此次发放的结果。

错误代码 err_code SYSTEMERROR String(32)

错误码信息

注意:出现未明确的错误码(SYSTEMERROR等)时,请务必用原商户订单号重试,或者再请求一次查询接口以确认此次发放的结果。

错误代码描述 err_code_des 系统错误 String(128) 结果信息描述

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

字段名 变量名 必填 示例值 类型 说明
商户订单号 mch_billno 10000098201411111234567890 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 100000000020150520314766074200 String(32) 微信红包订单号

成功示例:

<xml> 

   <return_code><![CDATA[SUCCESS]]></return_code> 

   <return_msg><![CDATA[发放成功.]]></return_msg> 

   <result_code><![CDATA[SUCCESS]]></result_code> 

   <err_code><![CDATA[0]]></err_code> 

   <err_code_des><![CDATA[发放成功.]]></err_code_des> 

   <mch_billno><![CDATA[0010010404201411170000046545]]></mch_billno> 

   <mch_id>10010404</mch_id> 

   <wxappid><![CDATA[wx6fa7e3bab7e15415]]></wxappid> 

   <re_openid><![CDATA[onqOjjmM1tad-3ROpncN-yUfa6uI]]></re_openid> 

   <total_amount>3</total_amount> 

   <send_time><![CDATA[20150227091010]]></send_time>

   <send_listid><![CDATA[1000000000201502270093647546]]></send_listid>

</xml>

失败示例:

<xml>

   <return_code><![CDATA[FAIL]]></return_code>

   <return_msg><![CDATA[系统繁忙,请稍后再试.]]></return_msg>

   <result_code><![CDATA[FAIL]]></result_code>

   <err_code><![CDATA[268458547]]></err_code>

   <err_code_des><![CDATA[系统繁忙,请稍后再试.]]></err_code_des>

   <mch_billno><![CDATA[0010010404201411170000046542]]></mch_billno>

   <mch_id>10010404</mch_id>

   <wxappid><![CDATA[wx6fa7e3bab7e15415]]></wxappid>

   <re_openid><![CDATA[onqOjjmM1tad-3ROpncN-yUfa6uI]]></re_openid>

   <total_amount>3</total_amount>

</xml>

错误码

错误码 描述 解决方案
NO_AUTH 发放失败,此请求可能存在风险,已被微信拦截 请提醒用户检查自身账号是否异常。使用常用的活跃的微信号可避免这种情况。
SENDNUM_LIMIT 该用户今日领取红包个数超过限制 如有需要、请在微信支付商户平台【api安全】中重新配置 【每日同一用户领取本商户红包不允许超过的个数】。
CA_ERROR 请求未携带证书,或请求携带的证书出错 到商户平台下载证书,请求带上证书后重试。
ILLEGAL_APPID 错误传入了app的appid 接口传入的所有appid应该为公众号的appid(在mp.weixin.qq.com申请的),不能为APP的appid(在open.weixin.qq.com申请的)。
SIGN_ERROR 商户签名错误 按文档要求重新生成签名后再重试。
FREQ_LIMIT 受频率限制 请对请求做频率控制
XML_ERROR 请求的xml格式错误,或者post的数据为空 检查请求串,确认无误后重试
PARAM_ERROR 参数错误 请查看err_code_des,修改设置错误的参数
红包祝福语、活动名称、备注、商户名称设置失败 请调整对应文案后重新再试
OPENID_ERROR Openid错误 根据用户在商家公众账号上的openid,获取用户在红包公众账号上的openid 错误。请核对商户自身公众号appid和用户在此公众号下的openid。
NOTENOUGH 余额不足 商户账号余额不足,请登录微信支付商户平台充值
FATAL_ERROR 重复请求时,参数与原单不一致 使用相同商户单号进行重复请求时,参数与第一次请求时不一致,请检查并修改参数后再重试。
SECOND_OVER_LIMITED 企业红包的按分钟发放受限 每分钟发送红包数量不得超过1800个;(可联系微信支付wxhongbao@tencent.com调高额度)
DAY_ OVER_LIMITED 企业红包的按天日发放受限 单个商户日发送红包数量不大于10000个;(可联系微信支付wxhongbao@tencent.com调高额度)
MONEY_LIMIT 红包金额发放限制 每个红包金额必须大于1元,小于1000元(可联系微信支付wxhongbao@tencent.com调高额度至4999元)
API_METHOD_CLOSED 你的商户号API发放方式已关闭,请联系管理员在商户平台开启 请联系管理员在商户平台开启
SEND_FAILED 红包发放失败,请更换单号再重试 原商户单号已经失败,如果还要对同一个用户发放红包, 需要更换新的商户单号再试。
SYSTEMERROR 系统繁忙,请再试。 可用同一商户单号再次调用,只会发放一个红包
PROCESSING 请求已受理,请稍后使用原单号查询发放结果 请在红包发放二十分钟后查询,按照查询结果成功失败进行处理,如果依然是PROCESSING的状态,请使用原商户订单号重试
SENDNUM_LIMIT 该用户今日领取红包个数超过限制 如有需要、请在微信支付商户平台【api安全】中重新配置 【每日同一用户领取本商户红包不允许超过的个数】。
SENDAMOUNT_LIMIT 您的商户号今日发放金额超过限制,如有需要请登录微信支付商户平台更改API安全配置 如有需要,请联系管理员在商户平台上调整单日发送金额上限。
RCVDAMOUNT_LIMIT 该用户今日领取金额超过限制,如有需要请登录微信支付商户平台更改API安全配置 如有需要,请联系管理员在商户平台上调整单用户单日领取金额上限。