發(fā)放紅包接口
發(fā)放規(guī)則
1.發(fā)送頻率限制------默認(rèn)30/秒
2.場景金額限制------默認(rèn)紅包金額為1-200元，如有需要，可前往商戶平臺進行設(shè)置和申請
3.其他限制------商戶單日出資金額上限--100萬元；單用戶單日收款金額上限--1000元；單用戶單日可領(lǐng)取紅包個數(shù)上限--10個.
注意事項：
- ◆ 紅包金額大于200或者小于1元時，請求參數(shù)scene_id必傳，參數(shù)說明見下文。
- ◆ 根據(jù)監(jiān)管要求，新申請商戶號使用小程序紅包需要滿足兩個條件：1、入駐時間超過90天 2、連續(xù)正常交易30天。
- ◆ 移動應(yīng)用的appid無法使用紅包接口。
- ◆ 當(dāng)返回錯誤碼為“SYSTEMERROR”時，請不要更換商戶訂單號，一定要使用原商戶訂單號重試，否則可能造成重復(fù)發(fā)放紅包等資金風(fēng)險。
- ◆ XML具有可擴展性，因此返回參數(shù)可能會有新增，而且順序可能不完全遵循此文檔規(guī)范，如果在解析回包的時候發(fā)生錯誤，請商戶務(wù)必不要換單重試，請商戶聯(lián)系客服確認(rèn)紅包發(fā)放情況。如果有新回包字段，會更新到此API文檔中。
- ◆ 因為錯誤代碼字段err_code的值后續(xù)可能會增加，所以商戶如果遇到回包返回新的錯誤碼，請商戶務(wù)必不要換單重試，請商戶聯(lián)系客服確認(rèn)紅包發(fā)放情況。如果有新的錯誤碼，會更新到此API文檔中。
- ◆ 錯誤代碼描述字段err_code_des只供人工定位問題時做參考，系統(tǒng)實現(xiàn)時請不要依賴這個字段來做自動化處理。
- ◆ 請商戶在自身的系統(tǒng)中合理設(shè)置發(fā)放頻次并做好并發(fā)控制，防范錯付風(fēng)險。
- ◆ 因商戶自身系統(tǒng)設(shè)置存在問題導(dǎo)致的資金損失，由商戶自行承擔(dān)。
接口調(diào)用請求說明
| 請求Url | https://api.mch.weixin.qq.com/mmpaymkttransfers/sendminiprogramhb |
|---|---|
| 是否需要證書 | 是（證書及使用說明詳見商戶證書） |
| 請求方式 | POST |
請求參數(shù)
| 字段名 | 字段 | 必填 | 示例值 | 類型 | 說明 |
|---|---|---|---|---|---|
| 隨機字符串 | nonce_str | 是 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | String(32) | 隨機字符串，不長于32位 |
| 簽名 | sign | 是 | C380BEC2BFD727A4B6845133519F3AD6 | String(32) | 詳見簽名生成算法 |
| 商戶訂單號 | mch_billno | 是 | 10000098201411111234567890 | String(28) | 商戶訂單號（每個訂單號必須唯一。取值范圍：0~9，a~z，A~Z） 組成： mch_id+yyyymmdd+10位一天內(nèi)不能重復(fù)的數(shù)字。 接口根據(jù)商戶訂單號支持重入， 如出現(xiàn)超時可再調(diào)用。 |
| 商戶號 | mch_id | 是 | 10000098 | String(32) | 微信支付分配的商戶號 |
| 小程序賬號appid | wxappid | 是 | wx8888888888888888 | String(32) | 微信為發(fā)放紅包商戶分配的小程序賬號ID，接口傳入的appid應(yīng)該為小程序的appid（在mp.weixin.qq.com申請的） 校驗規(guī)則： 1、該appid需要與接口傳入中的re_openid有對應(yīng)關(guān)系； 2、該appid需要與發(fā)放紅包商戶號有綁定關(guān)系，若未綁定，可參考該指引完成綁定（商家商戶號與AppID賬號關(guān)聯(lián)管理） |
| 商戶名稱 | send_name | 是 | 天虹百貨 | String(32) | 紅包發(fā)送者名稱 |
| 用戶openid | re_openid | 是 | oxTWIuGaIt6gTKsQRLau2M0yL16E | String(32) |
接受收紅包的用戶openid |
| 付款金額 | total_amount | 是 | 1000 | int | 付款金額，單位分 |
| 紅包發(fā)放總?cè)藬?shù) | total_num | 是 | 1 | int |
紅包發(fā)放總?cè)藬?shù) total_num=1 |
| 紅包祝福語 | wishing | 是 | 感謝您參加猜燈謎活動，祝您元宵節(jié)快樂！ | String(128) | 紅包祝福語 |
| 活動名稱 | act_name | 是 | 猜燈謎搶紅包活動 | String(32) | 活動名稱 |
| 備注 | remark | 是 | 猜越多得越多，快來搶！ | String(256) | 備注信息 |
| 通知用戶形式 | notify_way | 是 | MINI_PROGRAM_JSAPI |
String(256) | 通過JSAPI方式領(lǐng)取紅包,小程序紅包固定傳MINI_PROGRAM_JSAPI |
| 場景id | scene_id | 否 | PRODUCT_8 | String(32) |
發(fā)放紅包使用場景，紅包金額大于200時必傳 PRODUCT_1:商品促銷 PRODUCT_2:抽獎 PRODUCT_3:虛擬物品兌獎 PRODUCT_4:企業(yè)內(nèi)部福利 PRODUCT_5:渠道分潤 PRODUCT_6:保險回饋 PRODUCT_7:彩票派獎 PRODUCT_8:稅務(wù)刮獎 |
數(shù)據(jù)示例：
<xml> |
返回參數(shù)
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 說明 |
|---|---|---|---|---|---|
| 返回狀態(tài)碼 | return_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL 此字段是通信標(biāo)識，非交易標(biāo)識，交易是否成功需要查看result_code來判斷 |
| 返回信息 | return_msg | 否 | 簽名失敗 | String(128) | 返回信息，如非空，為錯誤原因 簽名失敗 參數(shù)格式校驗錯誤 |
| 以下字段在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) | 商戶appid，接口傳入的所有appid應(yīng)該為小程序賬號的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) | 紅包訂單的微信單號 |
| Jsapi的入?yún)?/td> | package | 是 | sendid=242e8abd163d300019b2cae74ba8e8c06e3f0e51ab84d16b3c80decd22a5b672&ver=8&sign=4110d649a5aef52dd6b95654ddf91ca7d5411ac159ace4e1a766b7d3967a1c3dfe1d256811445a4abda2d9cfa4a9b377a829258bd00d90313c6c346f2349fe5d&mchid=11475856&appid=wxd27ebc41b85ce36d | String | 返回jaspi的入?yún)ackage的值 |
成功示例：
<xml> |
失敗示例：
<xml> |
錯誤碼
| 錯誤碼 | 錯誤描述 | 原因 | 解決方式 |
|---|---|---|---|
| NO_AUTH | 發(fā)放失敗，此請求可能存在風(fēng)險，已被微信攔截 | 用戶賬號異常，被攔截 | 請?zhí)嵝延脩魴z查自身賬號是否異常。使用常用的活躍的微信號可避免這種情況。 |
| SENDNUM_LIMIT | 該用戶今日領(lǐng)取紅包個數(shù)超過限制 | 該用戶今日領(lǐng)取紅包個數(shù)超過你在微信支付商戶平臺配置的上限 | 如有需要、請在微信支付商戶平臺【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，但商戶單號未更新 | 請商戶檢查代碼實現(xiàn)邏輯 |
| 金額和原始單參數(shù)不一致 | 更換了金額，但商戶單號未更新 | 請商戶檢查代碼實現(xiàn)邏輯 | |
| CA_ERROR | CA證書出錯，請登錄微信支付商戶平臺下載證書 | 請求攜帶的證書出錯 | 到商戶平臺下載證書，請求帶上證書后重試 |
| SIGN_ERROR | 簽名錯誤 | 1、沒有使用商戶平臺設(shè)置的商戶API密鑰進行加密（有可能之前設(shè)置過密鑰，后來被修改了，沒有使用新的密鑰進行加密）。 2、加密前沒有按照文檔進行參數(shù)排序（可參考文檔） 3、把值為空的參數(shù)也進行了簽名。可到（http://mch.weixin.qq.com/wiki/tools/signverify/）驗證。 4、如果以上3步都沒有問題，把請求串中（post的數(shù)據(jù)）里面中文都去掉，換成英文，試下，看是否是編碼問題。（post的數(shù)據(jù)要求是utf8） |
1. 到商戶平臺重新設(shè)置新的密鑰后重試 2. 檢查請求參數(shù)把空格去掉重試 3. 中文不需要進行encode，使用CDATA 4. 按文檔要求生成簽名后再重試 在線簽名驗證工具：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 | 超過頻率限制,請稍后再試 | 受頻率限制 | 請對請求做頻率控制（可聯(lián)系微信支付wxhongbao@tencent.com申請調(diào)高） |
| 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)系校驗失敗 | 檢查下msgappid是否填寫錯誤，msgappid需要跟主、子商戶號 有綁定關(guān)系 |
| ACCEPTMODE_ERROR | 主、子商戶號關(guān)系校驗失敗 | 服務(wù)商模式下主商戶號與子商戶號關(guān)系校驗失敗 | 確認(rèn)傳入的主商戶號與子商戶號是否有受理關(guān)系 |
| PROCESSING | 請求已受理，請稍后使用原單號查詢發(fā)放結(jié)果 | 發(fā)紅包流程正在處理 | 二十分鐘后查詢,按照查詢結(jié)果成功失敗進行處理 |
| PARAM_ERROR | act_name字段必填,并且少于32個字符 | 請求的act_name字段填寫錯誤 | 填寫正確的act_name后重試 |
| 發(fā)放金額、最小金額、最大金額必須相等 | 請求的金額相關(guān)字段填寫錯誤 | 按文檔要求填寫正確的金額后重試 | |
| 紅包金額參數(shù)錯誤 | 紅包金額過大 | 修改金額重試 | |
| appid字段必填,最長為32個字符 | 請求的appid字段填寫錯誤 | 填寫正確的appid后重試 | |
| 訂單號字段必填,最長為28個字符 | 請求的mch_billno字段填寫錯誤 | 填寫正確的billno后重試 | |
| 輸入的商戶號有誤 | 請求的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)文案后重新再試 | |
SENDAMOUNT_LIMIT |
您的商戶號今日發(fā)放金額超過限制，如有需要請登錄微信支付商戶平臺更改API安全配置 |
商戶今日發(fā)放的總金額超過您在微信支付商戶平臺配置的上限 |
如有需要，請聯(lián)系管理員在商戶平臺上調(diào)整單日發(fā)送金額上限。 |
RCVDAMOUNT_LIMIT |
該用戶今日領(lǐng)取金額超過限制，如有需要請登錄微信支付商戶平臺更改API安全配置 |
該用戶今日領(lǐng)取紅包總金額超過您在微信支付商戶平臺配置的上限 |
如有需要，請聯(lián)系管理員在商戶平臺上調(diào)整單用戶單日領(lǐng)取金額上限。 |