查詢紅包記錄
使用說明
用于商戶對已發(fā)放的紅包進(jìn)行查詢紅包的具體信息,可支持普通紅包和裂變包。
注意事項(xiàng)
◆ 查詢紅包記錄API只支持查詢30天內(nèi)的紅包訂單,30天之前的紅包訂單請登錄商戶平臺查詢。
◆ 如果查詢單號對應(yīng)的數(shù)據(jù)不存在,那么數(shù)據(jù)不存在的原因可能是:(1)發(fā)放請求還在處理中;(2)紅包發(fā)放處理失敗導(dǎo)致紅包訂單沒有落地。在上述情況下,商戶首先需要檢查該商戶訂單號是否確實(shí)是自己發(fā)起的,如果商戶確認(rèn)是自己發(fā)起的,則請商戶不要直接當(dāng)做紅包發(fā)放失敗處理,請商戶隔幾分鐘再嘗試查詢,或者商戶可以通過相同的商戶訂單號再次發(fā)起發(fā)放請求。如果商戶誤把還在發(fā)放中的訂單直接當(dāng)發(fā)放失敗處理,商戶應(yīng)當(dāng)自行承擔(dān)因此產(chǎn)生的所有損失和責(zé)任。
◆ XML具有可擴(kuò)展性,因此返回參數(shù)可能會有新增,而且順序可能不完全遵循此文檔規(guī)范,如果在解析回包的時(shí)候發(fā)生錯(cuò)誤,請商戶務(wù)必不要換單重試,請商戶聯(lián)系客服確認(rèn)紅包發(fā)放情況。如果有新回包字段,會更新到此API文檔中。
◆ 因?yàn)殄e(cuò)誤代碼字段err_code的值后續(xù)可能會增加,所以商戶如果遇到回包返回新的錯(cuò)誤碼,請商戶務(wù)必不要換單重試,請商戶聯(lián)系客服確認(rèn)紅包發(fā)放情況。如果有新的錯(cuò)誤碼,會更新到此API文檔中。
◆ 錯(cuò)誤代碼描述字段err_code_des只供人工定位問題時(shí)做參考,系統(tǒng)實(shí)現(xiàn)時(shí)請不要依賴這個(gè)字段來做自動(dòng)化處理。
接口調(diào)用請求說明
請求Url | https://api.mch.weixin.qq.com/mmpaymkttransfers/gethbinfo |
---|---|
是否需要證書 | 是(證書及使用說明詳見商戶證書) |
請求方式 | POST |
請求參數(shù)
字段名 | 字段 | 必填 | 示例值 | 類型 | 說明 |
---|---|---|---|---|---|
隨機(jī)字符串 | nonce_str | 是 | 5K8264ILTKCH16CQ2502SI8ZNMTM67VS | String(32) | 隨機(jī)字符串,不長于32位 |
簽名 | sign | 是 | C380BEC2BFD727A4B6845133519F3AD6 | String(32) | 詳見簽名生成算法 |
商戶訂單號 | mch_billno | 是 | 10000098201411111234567890 | String(28) | 商戶發(fā)放紅包的商戶訂單號 |
商戶號 | mch_id | 是 | 10000098 | String(32) | 微信支付分配的商戶號 |
Appid | appid | 是 | wxe062425f740d30d8 | String(32) | 微信分配的公眾賬號ID(企業(yè)號corpid即為此appId),接口傳入的所有appid應(yīng)該為公眾號的appid(在mp.weixin.qq.com申請的),不能為APP的appid(在open.weixin.qq.com申請的)。 |
訂單類型 | bill_type | 是 | MCHT | String(32) | MCHT:通過商戶訂單號獲取紅包信息。 |
數(shù)據(jù)示例:
<sign><![CDATA[E1EE61A91C8E90F299DE6AE075D60A2D]]></sign>
<mch_billno><![CDATA[0010010404201411170000046545]]></mch_billno>
<mch_id><![CDATA[10000097]]></mch_id>
<appid><![CDATA[wxe062425f740c30d8]]></appid>
<bill_type><![CDATA[MCHT]]></ bill_type>
<nonce_str><![CDATA[50780e0cca98c8c8e814883e5caa672e]]></nonce_str>
</xml>
返回參數(shù)
字段名 | 變量名 | 必填 | 示例值 | 類型 | 說明 |
---|---|---|---|---|---|
返回狀態(tài)碼 | return_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL 此字段是通信標(biāo)識,非紅包發(fā)放結(jié)果標(biāo)識,紅包發(fā)放是否成功需要結(jié)合result_code以及status來判斷 |
返回信息 | return_msg | 否 | 簽名失敗 | String(128) | 返回信息,如非空,為錯(cuò)誤原因 簽名失敗 參數(shù)格式校驗(yàn)錯(cuò)誤 |
以下字段在return_code為SUCCESS的時(shí)候有返回
字段名 | 變量名 | 必填 | 示例值 | 類型 | 說明 |
---|---|---|---|---|---|
業(yè)務(wù)結(jié)果 | result_code | 是 | SUCCESS | String(16) | SUCCESS/FAIL 非紅包發(fā)放結(jié)果標(biāo)識,紅包發(fā)放是否成功需要查看status字段來判斷 |
錯(cuò)誤代碼 | err_code | 否 | SYSTEMERROR | String(32) | 錯(cuò)誤碼信息 |
錯(cuò)誤代碼描述 | err_code_des | 否 | 系統(tǒng)錯(cuò)誤 | String(128) | 結(jié)果信息描述 |
以下字段在return_code 和result_code都為SUCCESS的時(shí)候有返回
字段名 | 變量名 | 必填 | 示例值 | 類型 | 描述 | 商戶訂單號 | mch_billno | 是 | 10000098201411111234567890 | String(28) | 商戶使用查詢API填寫的商戶單號的原路返回 |
---|---|---|---|---|---|
商戶號 | mch_id | 是 | 10000098 | String(32) | 微信支付分配的商戶號 |
紅包單號 | detail_id | 是 | 1000000000201503283103439304 | String(32) | 使用API發(fā)放現(xiàn)金紅包時(shí)返回的紅包單號 |
紅包狀態(tài) | status | 是 | RECEIVED | string(16) | SENDING:發(fā)放中 SENT:已發(fā)放待領(lǐng)取 FAILED:發(fā)放失敗 RECEIVED:已領(lǐng)取 RFUND_ING:退款中 REFUND:已退款 |
發(fā)放類型 | send_type | 是 | API | String(32) | API:通過API接口發(fā)放 UPLOAD:通過上傳文件方式發(fā)放 ACTIVITY:通過活動(dòng)方式發(fā)放 |
紅包類型 | hb_type | 是 | GROUP | String(32) | GROUP:裂變紅包 NORMAL:普通紅包 |
紅包個(gè)數(shù) | total_num | 是 | 1 | int | 紅包個(gè)數(shù) |
紅包金額 | total_amount | 是 | 5000 | int | 紅包總金額(單位分) |
失敗原因 | reason | 否 | 余額不足 | String(32) | 發(fā)送失敗原因 |
紅包發(fā)送時(shí)間 | send_time | 是 | 2015-04-21 20:00:00 | String(32) | 紅包的發(fā)送時(shí)間 |
紅包退款時(shí)間 | refund_time | 否 | 2015-04-21 23:03:00 | String(32) | 紅包的退款時(shí)間(如果其未領(lǐng)取的退款) |
紅包退款金額 | refund_amount | 否 | 8000 | int | 紅包退款金額 |
祝福語 | wishing | 否 | 新年快樂 | String(128) | 祝福語 |
活動(dòng)描述 | remark | 否 | 新年紅包 | String(256) | 活動(dòng)描述,低版本微信可見 |
活動(dòng)名稱 | act_name | 否 | 新年紅包 | String(32) | 發(fā)紅包的活動(dòng)名稱 |
裂變紅包領(lǐng)取列表 | hblist | 否 | 內(nèi)容如下表 | array | 裂變紅包的領(lǐng)取列表 |
領(lǐng)取紅包的Openid | openid | 是 | ohO4GtzOAAYMp2yapORH3dQB3W18 | String(32) | 領(lǐng)取紅包的openid |
金額 | amount | 是 | 100 | int | 領(lǐng)取金額 |
接收時(shí)間 | rcv_time | 是 | 2015-04-21 20:00:00 | String(32) | 領(lǐng)取紅包的時(shí)間 |
成功示例:
<xml> <return_code><![CDATA[SUCCESS]]></return_code> <return_msg><![CDATA[OK]]></return_msg> <result_code><![CDATA[SUCCESS]]></result_code> <err_code><![CDATA[SUCCESS]]></err_code> <err_code_des><![CDATA[OK]]></err_code_des> <mch_billno><![CDATA[9010080799701411170000046603]]></mch_billno> <mch_id><![CDATA[11475856]]></mch_id> <detail_id><![CDATA[10000417012016080830956240040]]></detail_id> <status><![CDATA[RECEIVED]]></status> <send_type><![CDATA[ACTIVITY]]></send_type> <hb_type><![CDATA[NORMAL]]></hb_type> <total_num>1</total_num> <total_amount>100</total_amount> <send_time><![CDATA[2016-08-08 21:49:22]]></send_time> <hblist> <hbinfo> <openid><![CDATA[oHkLxtzmyHXX6FW_cAWo_orTSRXs]]></openid> <amount>100</amount> <rcv_time><![CDATA[2016-08-08 21:49:46]]></rcv_time> </hbinfo> </hblist> </xml> |
失敗示例:
<return_code><![CDATA[FAIL]]></return_code>
<return_msg><![CDATA[指定單號數(shù)據(jù)不存在]]></return_msg>
<result_code><![CDATA[FAIL]]></result_code>
<err_code><![CDATA[SYSTEMERROR]]></err_code>
<err_code_des><![CDATA[指定單號數(shù)據(jù)不存在]]></err_code_des>
<mch_id>666</mch_id>
<mch_billno><![CDATA[1000005901201407261446939688]]></mch_billno>
</xml>
5.錯(cuò)誤碼
錯(cuò)誤代碼 | 描述 | 解決方案 |
---|---|---|
CA_ERROR | 請求未攜帶證書,或請求攜帶的證書出錯(cuò) | 到商戶平臺下載證書,請求帶上證書后重試。 |
SIGN_ERROR | 商戶簽名錯(cuò)誤 | 按文檔要求重新生成簽名后再重試。 |
NO_AUTH | 沒有權(quán)限 | 請聯(lián)系微信支付開通api權(quán)限 |
NOT_FOUND | 指定單號數(shù)據(jù)不存在 | 查詢單號對應(yīng)的數(shù)據(jù)不存在,請使用正確的商戶訂單號查詢 |
FREQ_LIMIT | 受頻率限制 | 請對請求做頻率控制 |
XML_ERROR | 請求的xml格式錯(cuò)誤,或者post的數(shù)據(jù)為空 | 檢查請求串,確認(rèn)無誤后重試 |
PARAM_ERROR | 參數(shù)錯(cuò)誤 | 請查看err_code_des,修改設(shè)置錯(cuò)誤的參數(shù) |
SYSTEMERROR | 系統(tǒng)繁忙,請?jiān)僭嚒?/td> | 紅包系統(tǒng)繁忙。 |