功能
- 商户调用接口时,通过指定发送对象以及发送金额的方式发放红包。
- 领取到红包后,用户的资金直接进入微信零钱。
- 调用现金红包接口需要使用到证书,请前往商户平台下载证书。
- 因为发送现金红包是从商户平台余额扣款,所以商户平台的账户余额必须有充足的余额
接口
请求Url: https://api.mch.weixin.qq.com/mmpaymkttransfers/sendredpack
请求方式: POST
是否需要证书: 是
请求参数
nonce_str 随机字符串,长度不超32位(必选字段)
sign 签名(必选字段)
mch_billno 商户订单号,每个订单号必须唯一。接口根据商户订单号支持重入,如出现超时可再调用(必选字段)
mch_id 商户号,微信支付分配的商户号(必选字段)
wxappid 公众账号appid,微信分配的公众账号ID,接口传入的所有appid应该为公众号的appid (必选字段)
send_name 商户名称,红包发送者名称(必选字段)
re_openid 用户openid,接受红包的用户。用户在wxappid下的openid (必选字段)
total_amount 付款金额(必选字段)
total_num 红包发放总人数(必选字段)
wishing 红包祝福语(必选字段)
client_ip 调用接口的机器ip地址(必选字段)
act_name 活动名称(必选字段)
remark 备注信息(必选字段)
scene_id 发放红包使用场景,红包金额大于200时必传(非必选字段)
PRODUCT_1:商品促销
PRODUCT_2:抽奖
PRODUCT_3:虚拟物品兑奖
PRODUCT_4:企业内部福利
PRODUCT_5:渠道分润
PRODUCT_6:保险回馈
PRODUCT_7:彩票派奖
PRODUCT_8:税务刮奖
risk_info 活动信息(非必选字段)
consume_mch_id 资金授权商户号,服务商替特约商户发放时使用(非必选字段)
数据示例
<xml>
<sign><![CDATA[E1EE61A91C8E90F299DE6AE075D60A2D]]></sign>
<mch_billno><![CDATA[0010010404201411170000046545]]></mch_billno>
<mch_id><![CDATA[888]]></mch_id>
<wxappid><![CDATA[wxcbda96de0b165486]]></wxappid>
<send_name><![CDATA[send_name]]></send_name>
<re_openid><![CDATA[onqOjjmM1tad-3ROpncN-yUfa6uI]]></re_openid>
<total_amount><![CDATA[200]]></total_amount>
<total_num><![CDATA[1]]></total_num>
<wishing><![CDATA[恭喜发财]]></wishing>
<client_ip><![CDATA[127.0.0.1]]></client_ip>
<act_name><![CDATA[新年红包]]></act_name>
<remark><![CDATA[新年红包]]></remark>
<scene_id><![CDATA[PRODUCT_2]]></scene_id>
<consume_mch_id><![CDATA[10000097]]></consume_mch_id>
<nonce_str><![CDATA[50780e0cca98c8c8e814883e5caa672e]]></nonce_str>
<risk_info>posttime%3d123123412%26clientversion%3d234134%26mobile%3d122344545%26deviceid%3dIOS</risk_info>
</xml>
返回参数
return_code 返回状态码,此字段是通信标识,非交易标识,交易是否成功需要查看result_code来判断(必选字段)
return_msg 返回信息,为错误原因(非必选字段)
签名失败
参数格式校验错误
return_code为SUCCESS的时候返回
sign 签名(必选字段)
result_code 业务结果(必选字段)
err_code 错误代码(非必选字段)
err_code_des 错误代码描述(非必选字段)
在return_code和result_code都为SUCCESS的时候有返回
mch_billno 商户订单号,每个订单号必须唯一。
组成:mch_id+yyyymmdd+10位一天内不能重复的数字。(必选字段)
mch_id 商户号,微信支付分配的商户号(必选字段)
wxappid 公众账号,接口传入的所有appid应该为公众号的appid (必选字段)
re_openid 用户openid,接受收红包的用户(必选字段)
total_amount 付款金额(必选字段)
send_listid 微信单号,红包订单的微信单号(必选字段)
成功示例
<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>1</total_amount>
</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>1</total_amount>
</xml>
附注
签名算法
假设传送的参数如下:
appid: wxd930ea5d5a258f4f
mch_id: 10000100
device_info: 1000
body: test
nonce_str: ibuaiVcKdpRxkhJA
第一步,设所有发送或者接收到的数据为集合M,将集合M内非空参数值的参数按照参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA。
stringA="appid=wxd930ea5d5a258f4f&body=test&device_info=1000&mch_id=10000100&nonce_str=ibuaiVcKdpRxkhJA";
特别注意以下重要规则:
· 参数名ASCII码从小到大排序(字典序);
· 如果参数的值为空不参与签名;
· 参数名区分大小写;
· 验证调用返回或微信主动通知签名时,传送的sign参数不参与签名,将生成的签名与该sign值作校验。
· 微信接口可能增加字段,验证签名时必须支持增加的扩展字段
第二步,在stringA最后拼接上key得到stringSignTemp字符串,并对stringSignTemp进行MD5运算,再将得到的字符串所有字符转换为大写,得到sign值signValue。
key设置路径:微信商户平台(pay.weixin.qq.com)-->账户设置-->API安全-->密钥设置
stringSignTemp=stringA+"&key=192006250b4c09247ec02edce69f6a2d" //注:key为商户平台设置的密钥key
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7" //注:MD5签名方式
sign=hash_hmac("sha256",stringSignTemp,key).toUpperCase()="6A9AE1657590FD6257D693A078E1C3E4BB6BA4DC30B23E0EE2496E54170DACD6" //注:HMAC-SHA256签名方式
第三步,转化为xml格式发送到微信服务器。
<xml>
<appid>wxd930ea5d5a258f4f</appid>
<mch_id>10000100</mch_id>
<device_info>1000<device_info>
<body>test</body>
<nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
<sign>9A0A8659F005D6984697E2CA0A9CF3B7</sign>
<xml>