發(fā)放普通紅包
發(fā)放規(guī)則
1.發(fā)送頻率限制------默認(rèn)30/秒
2.場景金額限制------默認(rèn)紅包金額為1-200元，如有需要，可前往商戶平臺進(jìn)行設(shè)置和申請
3.其他限制------商戶單日出資金額上限--100萬元；單用戶單日收款金額上限--1000元；單用戶單日可領(lǐng)取紅包個數(shù)上限--10個；
注意事項(xiàng)：
◆ 紅包金額大于200或者小于1元時，請求參數(shù)scene_id必傳，參數(shù)說明見下文。
◆ 根據(jù)監(jiān)管要求，新申請商戶號使用現(xiàn)金紅包需要滿足兩個條件：1、入駐時間超過90天 2、連續(xù)正常交易30天。
◆ 移動應(yīng)用的appid無法使用紅包接口。
◆?當(dāng)返回錯誤碼為“SYSTEMERROR”時，請不要更換商戶訂單號，一定要使用原商戶訂單號重試，則可能造成重復(fù)發(fā)放紅包等資金風(fēng)險(xiǎn)。
◆?XML具有可擴(kuò)展性，因此返回參數(shù)可能會有新增，而且順序可能不完全遵循此文檔規(guī)范，如果在解析回包的時候發(fā)生錯誤，請商戶務(wù)必不要換單重試，請商戶聯(lián)系客服確認(rèn)紅包發(fā)放情況。如果有新回包字段，會更新到此API文檔中。
◆?因?yàn)殄e誤代碼字段err_code的值后續(xù)可能會增加，所以商戶如果遇到回包返回新的錯誤碼，請商戶務(wù)必不要換單重試，請商戶聯(lián)系客服確認(rèn)紅包發(fā)放情況。如果有新的錯誤碼，會更新到此API文檔中。
◆?錯誤代碼描述字段err_code_des只供人工定位問題時做參考，系統(tǒng)實(shí)現(xiàn)時請不要依賴這個字段來做自動化處理。
◆ 請商戶在自身的系統(tǒng)中合理設(shè)置發(fā)放頻次并做好并發(fā)控制，防范錯付風(fēng)險(xiǎn)。
◆ 因商戶自身系統(tǒng)設(shè)置存在問題導(dǎo)致的資金損失，由商戶自行承擔(dān)。
消息觸達(dá)規(guī)則
現(xiàn)金紅包發(fā)放后會以公眾號消息的形式觸達(dá)用戶，不同情況下觸達(dá)消息的形式會有差別，相關(guān)規(guī)則如下：
1.已關(guān)注公眾號的用戶，使用“防偽消息”觸達(dá)；
2.未關(guān)注公眾號的用戶，使用“模板消息”觸達(dá)。
接口調(diào)用請求說明
| 請求Url | https://api.mch.weixin.qq.com/mmpaymkttransfers/sendredpack |
|---|---|
| 是否需要證書 | 是（證書及使用說明詳見商戶證書） |
| 請求方式 | POST |
請求參數(shù)
| 字段名 | 字段 | 必填 | 示例值 | 類型 | 說明 |
|---|---|---|---|---|---|
| 隨機(jī)字符串 | nonce_str | 是 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | String(32) | 隨機(jī)字符串，不長于32位。 |
| 簽名 | sign | 是 | C380BEC2BFD727A4B6845133519F3AD6 | String(32) | 詳見簽名生成算法 |
| 商戶訂單號 | mch_billno | 是 | 10000098201411111234567890 | String(28) | 商戶訂單號（每個訂單號必須唯一。取值范圍：0~9，a~z，A~Z） 接口根據(jù)商戶訂單號支持重入，如出現(xiàn)超時可再調(diào)用。 |
| 商戶號 | mch_id | 是 | 10000098 | String(32) | 微信支付分配的商戶號 |
| 子商戶號 | sub_mch_id | 否 | 10000090 | String(32) | 微信支付分配的子商戶號，服務(wù)商模式下必填 |
| 公眾賬號appid | wxappid | 是 | wx8888888888888888 | String(32) | 微信分配的公眾賬號ID（企業(yè)號corpid即為此appId）。接口傳入的所有appid應(yīng)該為公眾號的appid（在mp.weixin.qq.com申請的），不能為APP的appid（在open.weixin.qq.com申請的）。
校驗(yàn)規(guī)則： 1、該appid需要與接口傳入中的re_openid有對應(yīng)關(guān)系； 2、該appid需要與發(fā)放紅包商戶號有綁定關(guān)系，若未綁定，可參考該指引完成綁定（商家商戶號與AppID賬號關(guān)聯(lián)管理） |
| 觸達(dá)用戶appid | msgappid | 是 | wx28b16568a629bb33 | String(32) | 服務(wù)商模式下觸達(dá)用戶時的appid(可填服務(wù)商自己的appid或子商戶的appid)，服務(wù)商模式下必填，服務(wù)商模式下填入的子商戶appid必須在微信支付商戶平臺中先錄入，否則會校驗(yàn)不過。 |
| 商戶名稱 | send_name | 是 | 天虹百貨 | String(32) | 紅包發(fā)送者名稱 |
| 用戶openid | re_openid | 是 | oxTWIuGaIt6gTKsQRLau2M0yL16E | String(32) |
接受紅包的用戶 用戶在wxappid下的openid，服務(wù)商模式下可填入msgappid下的openid。 |
| 付款金額 | total_amount | 是 | 1000 | int | 付款金額，單位分 |
| 紅包發(fā)放總?cè)藬?shù) | total_num | 是 | 1 | int |
紅包發(fā)放總?cè)藬?shù) total_num=1 |
| 紅包祝福語 | wishing | 是 | 感謝您參加猜燈謎活動，祝您元宵節(jié)快樂！ | String(128) | 紅包祝福語 |
| Ip地址 | client_ip | 是 | 192.168.0.1 | String(15) | 調(diào)用接口的機(jī)器Ip地址 |
| 活動名稱 | act_name | 是 | 猜燈謎搶紅包活動 | String(32) | 活動名稱 |
| 備注 | remark | 是 | 猜越多得越多，快來搶！ | String(256) | 備注信息 |
| 場景id | scene_id | 否 | PRODUCT_8 | String(32) | 發(fā)放紅包使用場景，紅包金額大于200或者小于1元時必傳 PRODUCT_1:商品促銷 PRODUCT_2:抽獎 PRODUCT_3:虛擬物品兌獎 PRODUCT_4:企業(yè)內(nèi)部福利 PRODUCT_5:渠道分潤 PRODUCT_6:保險(xiǎn)回饋 PRODUCT_7:彩票派獎 PRODUCT_8:稅務(wù)刮獎 |
| 活動信息 | risk_info | 否 | posttime%3d123123412%26clientversion%3d234134%26mobile%3d122344545%26deviceid%3dIOS | String(128) | posttime:用戶操作的時間戳 mobile:業(yè)務(wù)系統(tǒng)賬號的手機(jī)號，國家代碼-手機(jī)號。不需要+號 deviceid :mac 地址或者設(shè)備唯一標(biāo)識 clientversion :用戶操作的客戶端版本 把值為非空的信息用key=value進(jìn)行拼接，再進(jìn)行urlencode urlencode(posttime=xx& mobile =xx&deviceid=xx) |
數(shù)據(jù)示例：
<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[恭喜發(fā)財(cái)]]></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> <nonce_str><![CDATA[50780e0cca98c8c8e814883e5caa672e]]></nonce_str> <risk_info>posttime%3d123123412%26clientversion%3d234134%26mobile%3d122344545%26deviceid%3dIOS</risk_info> </xml> |
返回參數(shù)
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 說明 |
|---|---|---|---|---|---|
| 返回狀態(tài)碼 | return_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL 此字段是通信標(biāo)識，非紅包發(fā)放結(jié)果標(biāo)識，紅包發(fā)放是否成功需要查看result_code來判斷 |
| 返回信息 | return_msg | 否 | 簽名失敗 | String(128) | 返回信息，如非空，為錯誤原因 簽名失敗 參數(shù)格式校驗(yàn)錯誤 |
| 以下字段在return_code為SUCCESS的時候有返回 | |||||
| 業(yè)務(wù)結(jié)果 | result_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL 注意：當(dāng)狀態(tài)為FAIL時，存在業(yè)務(wù)結(jié)果未明確的情況。所以如果狀態(tài)是FAIL，請務(wù)必再請求一次查詢接口[請務(wù)必關(guān)注錯誤代碼（err_code字段），通過查詢得到的紅包狀態(tài)確認(rèn)此次發(fā)放的結(jié)果。]，以確認(rèn)此次發(fā)放的結(jié)果。 |
| 錯誤代碼 | err_code | 否 | SYSTEMERROR | String(32) | 錯誤碼信息 注意：出現(xiàn)未明確的錯誤碼（SYSTEMERROR等）時，請務(wù)必用原商戶訂單號重試，或者再請求一次查詢接口以確認(rèn)此次發(fā)放的結(jié)果。 |
| 錯誤代碼描述 | err_code_des | 否 | 系統(tǒng)錯誤 | String(128) | 結(jié)果信息描述 |
| 以下字段在return_code和result_code都為SUCCESS的時候有返回 | |||||
| 商戶訂單號 | mch_billno | 是 | 10000098201411111234567890 | String(28) | 商戶訂單號（每個訂單號必須唯一） 組成：mch_id+yyyymmdd+10位一天內(nèi)不能重復(fù)的數(shù)字 |
| 商戶號 | mch_id | 是 | 10000098 | String(32) | 微信支付分配的商戶號 |
| 公眾賬號appid | wxappid | 是 | wx8888888888888888 | String(32) | 微信為發(fā)放紅包商戶分配的公眾賬號ID，接口傳入的appid應(yīng)該為公眾號的appid或小程序的appid（在mp.weixin.qq.com申請的）或APP的appid（在open.weixin.qq.com申請的）。 校驗(yàn)規(guī)則： 1、該appid需要與接口傳入中的re_openid有對應(yīng)關(guān)系； 2、該appid需要與發(fā)放紅包商戶號有綁定關(guān)系，若未綁定，可參考該指引完成綁定（商家商戶號與AppID賬號關(guān)聯(lián)管理） |
| 用戶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[發(fā)放成功.]]></return_msg> <result_code><![CDATA[SUCCESS]]></result_code> <err_code><![CDATA[0]]></err_code> <err_code_des><![CDATA[發(fā)放成功.]]></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[系統(tǒng)繁忙,請稍后再試.]]></return_msg> <result_code><![CDATA[FAIL]]></result_code> <err_code><![CDATA[268458547]]></err_code> <err_code_des><![CDATA[系統(tǒng)繁忙,請稍后再試.]]></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> |
錯誤碼
| 錯誤碼 | 錯誤描述 | 原因 | 解決方式 |
|---|---|---|---|
| NO_AUTH | 發(fā)放失敗，此請求可能存在風(fēng)險(xiǎn)，已被微信攔截 | 用戶賬號異常，被攔截 | 請?zhí)嵝延脩魴z查自身賬號是否異常。使用常用的活躍的微信號可避免這種情況。 |
| SENDNUM_LIMIT | 該用戶今日領(lǐng)取紅包個數(shù)超過限制 | 該用戶今日領(lǐng)取紅包個數(shù)超過你在微信支付商戶平臺配置的上限 | 如有需要、請?jiān)谖⑿胖Ц渡虘羝脚_【api安全】中重新配置 【每日同一用戶領(lǐng)取本商戶紅包不允許超過的個數(shù)】。 |
| ILLEGAL_APPID | 非法appid，請確認(rèn)是否為公眾號的appid，不能為APP的appid | 錯誤傳入了app的appid | 接口傳入的所有appid應(yīng)該為公眾號的appid（在mp.weixin.qq.com申請的），不能為APP的appid（在open.weixin.qq.com申請的）。 |
| MONEY_LIMIT | 紅包金額發(fā)放限制 | 發(fā)送紅包金額不在限制范圍內(nèi) | 每個紅包金額必須在默認(rèn)額度內(nèi)（默認(rèn)大于1元，小于200元，可在產(chǎn)品設(shè)置中自行申請調(diào)高額度） |
| SEND_FAILED | 紅包發(fā)放失敗,請更換單號再重試 | 該紅包已經(jīng)發(fā)放失敗 | 如果需要重新發(fā)放，請更換單號再發(fā)放 |
| FATAL_ERROR | openid和原始單參數(shù)不一致 | 更換了openid，但商戶單號未更新 | 請商戶檢查代碼實(shí)現(xiàn)邏輯 |
| CA_ERROR | 商戶API證書校驗(yàn)出錯 | 請求沒帶商戶API證書或者帶上了錯誤的商戶API證書 | 您使用的調(diào)用證書有誤，請確認(rèn)是否使用了正確的證書，可以前往商戶平臺重新下載，證書需與商戶號對應(yīng)，如果要繼續(xù)付款必須使用原商戶訂單號重試。 |
| SIGN_ERROR | 簽名錯誤 | 1、沒有使用商戶平臺設(shè)置的商戶API密鑰進(jìn)行加密（有可能之前設(shè)置過密鑰，后來被修改了，沒有使用新的密鑰進(jìn)行加密）。 2、加密前沒有按照文檔進(jìn)行參數(shù)排序（可參考文檔） 3、把值為空的參數(shù)也進(jìn)行了簽名。可到（http://mch.weixin.qq.com/wiki/tools/signverify/ ）驗(yàn)證。 4、如果以上3步都沒有問題，把請求串中（post的數(shù)據(jù)）里面中文都去掉，換成英文，試下，看是否是編碼問題。（post的數(shù)據(jù)要求是utf8） |
1. 到商戶平臺重新設(shè)置新的密鑰后重試 2. 檢查請求參數(shù)把空格去掉重試 3. 中文不需要進(jìn)行encode，使用CDATA 4. 按文檔要求生成簽名后再重試 在線簽名驗(yàn)證工具：http://mch.weixin.qq.com/wiki/tools/signverify/ |
| SYSTEMERROR | 請求已受理，請稍后使用原單號查詢發(fā)放結(jié)果 | 系統(tǒng)無返回明確發(fā)放結(jié)果 | 使用原單號調(diào)用接口，查詢發(fā)放結(jié)果，如果使用新單號調(diào)用接口，視為新發(fā)放請求 |
| XML_ERROR | 輸入xml參數(shù)格式錯誤 | 請求的xml格式錯誤，或者post的數(shù)據(jù)為空 | 檢查請求串，確認(rèn)無誤后重試 |
| FREQ_LIMIT | 超過頻率限制,請稍后再試 | 受頻率限制 | 請對請求做頻率控制 |
| API_METHOD_CLOSED | 你的商戶號API發(fā)放方式已關(guān)閉，請聯(lián)系管理員在商戶平臺開啟 | 商戶API發(fā)放方式處于關(guān)閉狀態(tài) | 請聯(lián)系管理員在商戶平臺開啟 |
| NOTENOUGH | 賬號余額不足，請到商戶平臺充值后再重試 | 賬戶余額不足 | 充值后重試 |
| OPENID_ERROR | openid和appid不匹配 | openid和appid不匹配 | 發(fā)紅包的openid必須是本appid下的openid |
| MSGAPPID_ERROR | 觸達(dá)消息給用戶appid有誤 | msgappid與主、子商戶號的綁定關(guān)系校驗(yàn)失敗 | 檢查下msgappid是否填寫錯誤，msgappid需要跟主、子商戶號 有綁定關(guān)系 |
| ACCEPTMODE_ERROR | 主、子商戶號關(guān)系校驗(yàn)失敗 | 服務(wù)商模式下主商戶號與子商戶號關(guān)系校驗(yàn)失敗 | 確認(rèn)傳入的主商戶號與子商戶號是否有受理關(guān)系 |
| PROCESSING | 請求已受理，請稍后使用原單號查詢發(fā)放結(jié)果 | 紅包正在發(fā)放中 | 請?jiān)诩t包發(fā)放二十分鐘后查詢,按照查詢結(jié)果成功失敗進(jìn)行處理，如果依然是PROCESSING的狀態(tài)，請使用原商戶訂單號重試 |
| PARAM_ERROR | act_name字段必填,并且少于32個字符 | 請求的act_name字段填寫錯誤 | 填寫正確的act_name后重試 |
| 發(fā)放金額、最小金額、最大金額必須相等 | 請求的金額相關(guān)字段填寫錯誤 | 按文檔要求填寫正確的金額后重試 | |
| 紅包金額參數(shù)錯誤 | 紅包金額過大 | 修改金額重試 | |
| appid字段必填,最長為32個字符 | 請求的appid字段填寫錯誤 | 填寫正確的appid后重試 | |
| 訂單號字段必填,最長為28個字符 | 請求的mch_billno字段填寫錯誤 | 填寫正確的billno后重試 | |
| client_ip必須是合法的IP字符串 | 請求的client_ip填寫不正確 | 填寫正確的IP后重試 | |
| 輸入的商戶號有誤 | 請求的mchid字段非法（或者沒填） | 填寫對應(yīng)的商戶號再重試 | |
| 找不到對應(yīng)的商戶號 | 請求的mchid字段填寫錯誤 | 填寫正確的mchid字段后重試 | |
| nick_name字段必填，并且少于16字符 | 請求的nick_name字段錯誤 | 按文檔填寫正確的nick_name后重試 | |
| nonce_str字段必填,并且少于32字符 | 請求的nonce_str字段填寫不正確 | 按文檔要求填寫正確的nonce_str值后重試 | |
| re_openid字段為必填并且少于32個字符 | 請求的re_openid字段非法 | 填寫對re_openid后重試 | |
| remark字段為必填,并且少于256字符 | 請求的remark字段填寫錯誤 | 填寫正確的remark后重試 | |
| send_name字段為必填并且少于32字符 | 請求的send_name字段填寫不正確 | 按文檔填寫正確的send_name字段后重試 | |
| total_num必須為1 | total_num字段值不為1 | 修改total_num值為1后重試 | |
| wishing字段為必填,并且少于128個字符 | 缺少wishing字段 | 填寫wishing字段再重試 | |
| 商戶號和wxappid不匹配 | 商戶號和wxappid不匹配 | 請修改Mchid或wxappid參數(shù) | |
| 紅包祝福語、活動名稱、備注、商戶名稱設(shè)置失敗 | 紅包祝福語、活動名稱、備注、商戶名稱設(shè)置失敗 | 請調(diào)整對應(yīng)文案后重新再試 | |
| SENDNUM_LIMIT | 該用戶今日領(lǐng)取紅包個數(shù)超過限制 | 該用戶今日領(lǐng)取紅包個數(shù)超過你在微信支付商戶平臺配置的上限 | 如有需要、請?jiān)谖⑿胖Ц渡虘羝脚_【api安全】中重新配置 【每日同一用戶領(lǐng)取本商戶紅包不允許超過的個數(shù)】。 |
| SENDAMOUNT_LIMIT | 您的商戶號今日發(fā)放金額超過限制，如有需要請登錄微信支付商戶平臺更改API安全配置 | 商戶今日發(fā)放的總金額超過您在微信支付商戶平臺配置的上限 | 如有需要，請聯(lián)系管理員在商戶平臺上調(diào)整單日發(fā)送金額上限。 |
| RCVDAMOUNT_LIMIT | 該用戶今日領(lǐng)取金額超過限制，如有需要請登錄微信支付商戶平臺更改API安全配置 | 該用戶今日領(lǐng)取紅包總金額超過您在微信支付商戶平臺配置的上限 | 如有需要，請聯(lián)系管理員在商戶平臺上調(diào)整單用戶單日領(lǐng)取金額上限。 |