發(fā)放代金券
場景介紹
用于商戶主動調(diào)用接口給用戶發(fā)放代金券的場景，已做防小號處理，給小號發(fā)放代金券將返回錯誤碼。
注意：通過接口發(fā)放的代金券不會進(jìn)入微信卡包
接口請求鏈接
https://api.mch.weixin.qq.com/mmpaymkttransfers/send_coupon
是否需要證書
請求需要雙向證書。 詳見證書使用
請求參數(shù)
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 說明 |
|---|---|---|---|---|---|
| 代金券批次id | coupon_stock_id | 是 | 1757 | String | 代金券批次id |
| openid記錄數(shù) | openid_count | 是 | 1 | int | openid記錄數(shù)（目前支持num=1） |
| 商戶單據(jù)號 | partner_trade_no | 是 | 1000009820141203515766 | String | 商戶此次發(fā)放憑據(jù)號（格式：商戶id+日期+流水號），商戶側(cè)需保持唯一性 |
| 用戶openid | openid | 是 | onqOjjrXT-776SpHnfexGm1_P7iE | String | Openid信息，用戶在appid下的唯一標(biāo)識 |
| 公眾賬號ID | appid | 是 | wx5edab3bdfba3dc1c | String(32) | 微信為發(fā)券方商戶分配的公眾賬號ID，接口傳入的所有appid應(yīng)該為公眾號的appid（在mp.weixin.qq.com申請的），不能為APP的appid（在open.weixin.qq.com申請的）。 |
| 商戶號 | mch_id | 是 | 10000098 | String(32) | 微信為發(fā)券方商戶分配的商戶號 |
| 操作員 | op_user_id | 否 | 10000098 | String(32) | 操作員賬號, 默認(rèn)為商戶號 可在商戶平臺配置操作員對應(yīng)的api權(quán)限 |
| 設(shè)備號 | device_info | 否 | 013467007045764 | String(32) | 微信支付分配的終端設(shè)備號 |
| 隨機(jī)字符串 | nonce_str | 是 | 1417574675 | String(32) | 隨機(jī)字符串，不長于32位 |
| 簽名 | sign | 是 | 841B3002FE2220C87A2D08ABD8A8F791 | String(32) | 簽名參數(shù)，詳見簽名生成算法 |
| 協(xié)議版本 | version | 否 | 1.0 | String(32) | 默認(rèn)1.0 |
| 協(xié)議類型 | type | 否 | XML | String(32) | XML【目前僅支持默認(rèn)XML】 |
請求參數(shù)示例：
<xml>
<appid> wx5edab3bdfba3dc1c</appid>
<coupon_stock_id>1757</coupon_stock_id>
<mch_id>10010405</mch_id>
<nonce_str>1417574675</nonce_str>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<openid_count>1</openid_count>
<partner_trade_no>1000009820141203515766</partner_trade_no>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
</xml>
<appid> wx5edab3bdfba3dc1c</appid>
<coupon_stock_id>1757</coupon_stock_id>
<mch_id>10010405</mch_id>
<nonce_str>1417574675</nonce_str>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<openid_count>1</openid_count>
<partner_trade_no>1000009820141203515766</partner_trade_no>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
</xml>
CURL請求帶證書代碼樣例：
curl --cert 10010405.pem --key 10010405.key -H
"Content-Type：text/xml" -d
'<xml><mch_id>10010405</mch_id><appid>121512345</appid><nonce_str>1417582740</nonce_str><coupon_stock_id>1757</coupon_stock_id><openid_count>1</openid_count><openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid><partner_trade_no>121512345456</partner_trade_no></xml>' https://api.mch.weixin.qq.com/secapi/promotion/send_coupon/ -i返回參數(shù)
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 說明 |
|---|---|---|---|---|---|
| 返回狀態(tài)碼 | return_code | 是 | SUCCESS或者FAIL | String(16) |
SUCCESS/FAIL 此字段是通信標(biāo)識，非交易標(biāo)識，交易是否成功需要查看result_code來判斷 |
| 返回信息 | return_msg | 否 | 成功：返回空 | String(128) | 返回信息，如非空，為通信錯誤原因 |
| 公眾賬號ID | appid | 是 | wx5edab3bdfba3dc1c | String(32) | 微信為發(fā)券方商戶分配的公眾賬號ID，接口傳入的所有appid應(yīng)該為公眾號的appid（在mp.weixin.qq.com申請的），不能為APP的appid（在open.weixin.qq.com申請的）。 |
| 商戶號 | mch_id | 是 | 10000098 | String(32) | 微信為發(fā)券方商戶分配的商戶號 |
| 設(shè)備號 | device_info | 否 | 123456sb | String(32) | 微信支付分配的終端設(shè)備號， |
| 隨機(jī)字符串 | nonce_str | 是 | 1417574675 | String(32) | 隨機(jī)字符串，不長于32位 |
| 簽名 | sign | 是 | 841B3002FE2220C87A2D08ABD8A8F791 | String(32) | 對返回參數(shù)簽名計(jì)算后得到的簽名值 |
| 業(yè)務(wù)結(jié)果 | result_code | 是 | SUCCESS或者FAIL | String(16) | SUCCESS/FAIL |
| 錯誤代碼 | err_code | 否 | PARAM_ERROR | String(32) | 詳見業(yè)務(wù)錯誤代碼章節(jié) |
| 錯誤代碼描述 | err_code_des | 否 | 錯誤描述信息 | String(128) | 對錯誤信息的描述 |
| 代金券批次id | coupon_stock_id | 是 | 1757 | String | 創(chuàng)建代金券時生成的批次號，可在商戶平臺-代金券管理頁面查看 |
| 返回記錄數(shù) | resp_count | 是 | 1 | int | 返回記錄數(shù) |
| 成功記錄數(shù) | success_count | 是 | 1或者0 | int | 成功記錄數(shù) |
| 失敗記錄數(shù) | failed_count | 是 | 1或者0 | int | 失敗記錄數(shù) |
| 用戶標(biāo)識 | openid | 是 | onqOjjrXT-776SpHnfexGm1_P7iE | String | 用戶在商戶appid下的唯一標(biāo)識 |
| 代金券id | coupon_id | 是 | 1870 | String |
對一個用戶成功發(fā)放代金券則返回代金券id，即ret_code為SUCCESS的時候； 如果ret_code為FAILED則填寫空串"" |
| 返回信息 | ret_msg | 是 | 失敗描述信息，例如：“用戶已達(dá)領(lǐng)用上限” | String | 返回信息，當(dāng)返回碼是FAILED的時候填寫，否則填空串“” |
返回參數(shù)示例：
成功示例格式：
<xml>
<return_code>SUCCESS</return_code>
<appid>wx5edab3bdfba3dc1c</appid>
<mch_id>10000098</mch_id>
<nonce_str>1417579335</nonce_str>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
<result_code>SUCCESS</result_code>
<coupon_stock_id>1717</coupon_stock_id>
<resp_count>1</resp_count>
<success_count>1</success_count>
<failed_count>0</failed_count>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<ret_code>SUCCESS</ret_code>
<coupon_id>6954</coupon_id>
</xml>
<return_code>SUCCESS</return_code>
<appid>wx5edab3bdfba3dc1c</appid>
<mch_id>10000098</mch_id>
<nonce_str>1417579335</nonce_str>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
<result_code>SUCCESS</result_code>
<coupon_stock_id>1717</coupon_stock_id>
<resp_count>1</resp_count>
<success_count>1</success_count>
<failed_count>0</failed_count>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<ret_code>SUCCESS</ret_code>
<coupon_id>6954</coupon_id>
</xml>
失敗示例格式：
<xml>
? <return_code>SUCCESS</return_code>
? <appid>wx5edab3bdfba3dc1c</appid>
? <mch_id>10000098</mch_id>
? <nonce_str>1417579335</nonce_str>
? <sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
? <result_code>FAIL</result_code>
? <err_code>268456007</err_code>
? <err_code_des>你已領(lǐng)取過該代金券</err_code_des>
? <coupon_stock_id>1717</coupon_stock_id>
? <resp_count>1</resp_count>
? <success_count>0</success_count>
? <failed_count>1</failed_count>
? <openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
? <ret_code>FAIL</ret_code>
? <ret_msg>你已領(lǐng)取過該代金券</ret_msg>
? <coupon_id></coupon_id>
</xml>
? <return_code>SUCCESS</return_code>
? <appid>wx5edab3bdfba3dc1c</appid>
? <mch_id>10000098</mch_id>
? <nonce_str>1417579335</nonce_str>
? <sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
? <result_code>FAIL</result_code>
? <err_code>268456007</err_code>
? <err_code_des>你已領(lǐng)取過該代金券</err_code_des>
? <coupon_stock_id>1717</coupon_stock_id>
? <resp_count>1</resp_count>
? <success_count>0</success_count>
? <failed_count>1</failed_count>
? <openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
? <ret_code>FAIL</ret_code>
? <ret_msg>你已領(lǐng)取過該代金券</ret_msg>
? <coupon_id></coupon_id>
</xml>
錯誤碼
| 錯誤代碼 | 描述 | 解決方案 |
|---|---|---|
| STOCK_NOT_EXIST | 批次不存在 | 請檢查請求參數(shù)中填寫的代金券批次id和商戶號是否正確 |
| BLOCKED_BY_SPAMCHK | 小號攔截 | 當(dāng)前發(fā)放用戶為小號，根據(jù)風(fēng)險管控規(guī)則不允許給小號發(fā)放。 |
| DAY_BUDGET_NOT_ENOUGH | 批次達(dá)到單天發(fā)放預(yù)算上限 | 發(fā)券數(shù)量已經(jīng)達(dá)到單天發(fā)放上限，可在商戶平臺批次詳情頁修改單天發(fā)放預(yù)算 |
| USER_AL_GET_COUPON | 你已領(lǐng)取過該代金券 | 用戶已領(lǐng)過，正常邏輯報錯 |
| NETWORK ERROR | 網(wǎng)絡(luò)環(huán)境不佳，請重試 | 請重試 |
| AL_STOCK_OVER | 活動已結(jié)束 | 活動已結(jié)束，屬于正常邏輯錯誤 |
| FREQ_OVER_LIMIT | 超過發(fā)放頻率限制，請稍后再試 | 請控制發(fā)放請求的頻率 |
| PARAM_ERROR | 校驗(yàn)參數(shù)錯誤（會返回具體哪個參數(shù)錯誤） | 根據(jù)錯誤提示確認(rèn)參數(shù)無誤并更正 |
| SIGN_ERROR | 簽名錯誤 | 驗(yàn)證簽名有誤 |
| CA_ERROR | 證書有誤 | 確認(rèn)證書正確，或者聯(lián)系商戶平臺更新證書 |
| REQ_PARAM_XML_ERR | 輸入?yún)?shù)xml格式有誤 | 檢查入?yún)⒌膞ml格式是否正確 |
| COUPON_STOCK_ID_EMPTY | 批次ID為空 | 確保批次id正確傳入 |
| MCH_ID_EMPTY | 商戶ID為空 | 確保商戶id正確傳入 |
| CODE_2_ID_ERR | 商戶id有誤 | 檢查商戶id是否正確并合法 |
| OPEN_ID_EMPTY | 用戶openid為空 | 檢查用戶openid是否正確并合法 |
| ERR_VERIFY_SSL_SERIAL | 獲取客戶端證書序列號失敗! | 檢查證書是否正確 |
| ERR_VERIFY_SSL_SN | 獲取客戶端證書特征名稱(DN)域失敗! | 檢查證書是否正確 |
| CA_VERIFY_FAILED | 證書驗(yàn)證失敗 | 檢查證書是否正確 |
| STOCK_IS_NOT_VALID | 抱歉，該代金券已失效 | 代金券已失效，請確認(rèn)代金券的有效性，重新請求 |
| STOCK_AMOUNT_NOT_ENOUGH | 代金券批次預(yù)算不足 | 商戶可為該代金券批次追加預(yù)算后繼續(xù)發(fā)券 |
| MCH_NO_AUTH | 商戶無權(quán)限操作 | 該商戶無權(quán)限進(jìn)行該操作，請前往商戶平臺開通代金券權(quán)限 |
| ACCOUNTERROR | 賬號行為異常，無法領(lǐng)券 | 請求的代金券批次已在商戶平臺開啟風(fēng)險攔截功能，命中的用戶無法領(lǐng)券，如需給用戶發(fā)券，可創(chuàng)建不開啟攔截的批次重發(fā)，或聯(lián)系微信支付客服。 |