H5發(fā)券API
最新更新時(shí)間：2021.05.19 版本說(shuō)明
微信支付為商戶(hù)提供H5發(fā)券接口，可在H5頁(yè)面為指定用戶(hù)發(fā)放指定批次的微信支付商家券。推薦使用 JSAPI H5發(fā)券功能，兩者區(qū)別如下：
1. JSAPI H5發(fā)券功能 發(fā)券后會(huì)回調(diào)領(lǐng)券結(jié)果給到商家，方便商家做對(duì)應(yīng)的處理；該H5發(fā)券不回調(diào)信息給商家，依賴(lài)商家主動(dòng)去查詢(xún)。
2. 支持小程序嵌套H5場(chǎng)景的發(fā)券，該H5發(fā)券不支持在小程序內(nèi)進(jìn)行調(diào)用。
原理：H5發(fā)券的領(lǐng)券頁(yè)面是帶有weixin域名的一個(gè)H5頁(yè)面，不支持在商家小程序調(diào)用（因?yàn)樯碳覜](méi)有這個(gè)域名的備案資質(zhì)）；而jsapi發(fā)券的領(lǐng)券頁(yè)面是原生頁(yè)面，不受小程序框架約束。
H5接入操作
1、發(fā)券方式
用戶(hù)在商戶(hù)H5頁(yè)面觸發(fā)領(lǐng)券操作后，通過(guò)Url跳轉(zhuǎn)，由商戶(hù)H5重定向至指定微信支付H5頁(yè)面(https://action.weixin.qq.com/busifavor/getcouponinfo)并添加指定參數(shù)，用戶(hù)在微信支付H5頁(yè)面中點(diǎn)擊領(lǐng)券后，將自動(dòng)給用戶(hù)發(fā)券。
注：每一個(gè)H5領(lǐng)券域名后，都需添加#wechat_redirect，否則會(huì)報(bào)錯(cuò)，返回268435461錯(cuò)誤碼
https://action.weixin.qq.com/busifavor/getcouponinfo?stock_id=1234567890000000&out_request_no=201911280000&sign=D0D028212D200DC9DASDFSDFFD3676BEAD03046DC3A2E82A64C784EFFAF&send_coupon_merchant=123456789&open_id=oiSFDIOoijdsf#wechat_redirect
2、URL中參數(shù)
商戶(hù)需在Url中攜帶用戶(hù)信息及批次信息方可正常發(fā)券，具體參數(shù)如下：
| 參數(shù)名 | 變量 | 類(lèi)型[長(zhǎng)度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 批次號(hào) | stock_id | string[1,20] | 是 | 微信支付商家券批次號(hào) |
| 發(fā)券憑證 | out_request_no | string[1,128] | 是 | 發(fā)券憑證（示例格式：商戶(hù) id+日期+流水號(hào)），可包含英文字母、數(shù)字，不允許出現(xiàn)其他不合法符號(hào)，商戶(hù)側(cè)需保證發(fā)放憑據(jù)號(hào)唯一性 |
| 簽名 | sign | string | 是 | 簽名計(jì)算值。 簽名方式：HMAC-SHA256。 簽名規(guī)則：詳見(jiàn)《V2 簽名規(guī)則》 參與簽名字段說(shuō)明 注意：為了安全，簽名必須在后臺(tái)服務(wù)器計(jì)算，禁止在H5中計(jì)算，簽名 key 為微信支付 apiv2 的 signkey 示例值：9A0A8659F005D6984697E2CA0A9CF3B79A0A8659F005D6984697E2CA0A9CF3B7 |
| 發(fā)券商戶(hù)號(hào) | send_coupon_merchant | string[8,15] | 是 | 調(diào)用發(fā)券接口的商戶(hù)號(hào) |
| 用戶(hù)openid | open_id | string[1,128] | 是 | 目標(biāo)發(fā)券的用戶(hù)openid 校驗(yàn)規(guī)則： 1，可用歸屬商戶(hù)號(hào)綁定的APPID獲取的openid 2，可用發(fā)券商戶(hù)綁定的APPID獲取的openid 獲取openid請(qǐng)查看文檔 |
| 自定義領(lǐng)取時(shí)間 | customize_send_time{n} | string[1,32] | 否 | 商家券在商戶(hù)業(yè)務(wù)系統(tǒng)里的實(shí)際領(lǐng)取時(shí)間，僅針對(duì)有設(shè)置相對(duì)領(lǐng)取時(shí)間的批次生效（即批次有設(shè)置“生效后N天內(nèi)有效”或“領(lǐng)取后N天開(kāi)始生效”時(shí)間字段）。傳入后，將使用傳入的時(shí)間點(diǎn)，做為商家券領(lǐng)取時(shí)間來(lái)計(jì)算有效期，而非用戶(hù)在微信支付系統(tǒng)中點(diǎn)擊領(lǐng)取的時(shí)間 。 遵循rfc3339標(biāo)準(zhǔn)格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開(kāi)頭，HH:mm:ss表示時(shí)分秒，TIMEZONE表示時(shí)區(qū)（+08:00表示東八區(qū)時(shí)間，領(lǐng)先UTC 8小時(shí)，即北京時(shí)間）。例如：2015-05-20T13:29:35.+08:00表示，北京時(shí)間2015年5月20日 13點(diǎn)29分35秒。 注：該字段未啟用 示例值：2015-05-20T13:29:35+08:00 |
| 券 code | coupon_code | string[1,128] | 否 | 如果批次配置了 code 模式為“商戶(hù)發(fā)放時(shí)接口指定券 code”，則必填，其他模式無(wú)需填寫(xiě) 示例值：75345199 |
參與簽名字段說(shuō)明
| 參數(shù)名 | 變量 | 類(lèi)型[長(zhǎng)度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 批次號(hào) | stock_id | string[1,20] | 是 | 微信支付券批次id 示例值：123 |
| 發(fā)券憑證 | out_request_no | string[1,128] | 是 | 發(fā)券憑證，
可包含英文字母，數(shù)字，｜，_，*，-等內(nèi)容，不允許出現(xiàn)其他不合法符號(hào)，需在單個(gè)批次單個(gè)用戶(hù)下確保唯一性 示例值：1234567 |
| 發(fā)券商戶(hù)號(hào) | send_coupon_merchant | string[8,15] | 是 | 發(fā)券商戶(hù)號(hào) 示例值：10016226 |
| 用戶(hù)openid | open_id | string[1,128] | 是 | 目標(biāo)發(fā)券的用戶(hù)openid 示例值：10011212261 |
| 券 code | coupon_code | string[1,128] | 否 | 如果批次配置了 code 模式為“商戶(hù)發(fā)放時(shí)接口指定券 code”，則必填，其他模式無(wú)需填寫(xiě) 示例值：75345199 |
coupon_code=75345199&open_id=ow8uG5EM11Cnm&out_request_no=20191204550002&send_coupon_merchant=232323234&stock_id=12111100000001&key=3a5bc16abcdd22222
返回處理
由于H5發(fā)券采用的是Url重定向的形式，故無(wú)法直接將發(fā)券結(jié)果返回給商戶(hù)。
建議商戶(hù)調(diào)用【根據(jù)過(guò)濾條件查詢(xún)用戶(hù)券】接口及【查詢(xún)用戶(hù)單張券詳情】接口，查詢(xún)發(fā)券接口。
舉例：用戶(hù)領(lǐng)券完成并返回商家H5后，商家可自行觸發(fā)刷新事件，使用【根據(jù)過(guò)濾條件查詢(xún)用戶(hù)券】接口，通過(guò)創(chuàng)建商戶(hù)號(hào)、批次號(hào)、openid，查詢(xún)用戶(hù)是否已成功領(lǐng)取指定批次券，以及領(lǐng)取券的具體code。
錯(cuò)誤碼
如果發(fā)券失敗，錯(cuò)誤碼將在發(fā)券結(jié)果頁(yè)面展示給用戶(hù)及開(kāi)發(fā)者，開(kāi)發(fā)者可根據(jù)該頁(yè)面展示的錯(cuò)誤碼查詢(xún)失敗原因。
為保證用戶(hù)體驗(yàn)，部分易懂的錯(cuò)誤原因?qū)⒅苯诱故窘o用戶(hù)。
發(fā)券結(jié)果（send_coupon_result）中的錯(cuò)誤碼
| 錯(cuò)誤碼 | 描述 | 解決方案 |
|---|---|---|
| 268455936 | 發(fā)券參數(shù)錯(cuò)誤，請(qǐng)檢查發(fā)券參數(shù) | 請(qǐng)檢查發(fā)券參數(shù) |
| 272758302，272756756 | 批次已過(guò)期 | 請(qǐng)檢查批次時(shí)間 |
| 272758303，272756737，272757763 | 批次預(yù)算不足 | 請(qǐng)檢查批次預(yù)算 |
| 272756738 | 該批次已達(dá)到單天發(fā)放上限 | 請(qǐng)檢查批次單天發(fā)放上限 |
| 272756740 | 用戶(hù)領(lǐng)取券張數(shù)已達(dá)上限 | 請(qǐng)檢查用戶(hù)領(lǐng)取情況 |
| 272756753 | 用戶(hù)已領(lǐng)取過(guò)這張券 | 請(qǐng)檢查用戶(hù)領(lǐng)取情況 |
| 272756739 | 自然人限領(lǐng)攔截 | 請(qǐng)停止發(fā)放給該用戶(hù) |
| 272756743 | 批次狀態(tài)不合法，檢查該批次是否處于運(yùn)營(yíng)中 | 請(qǐng)檢查批次狀態(tài) |
| 272756762? | 指定Code發(fā)券模式下， 當(dāng)前發(fā)券Code已被使用 | 請(qǐng)更換Code后重試 |
| 272755722 | 批次不存在 | 請(qǐng)檢查批次號(hào)是否正確 |
| 272755713 | 用戶(hù)安全防刷攔截（潛在羊毛黨、黑產(chǎn)用戶(hù)） | 請(qǐng)停止發(fā)放給該用戶(hù) |
| 272758292 | 未獲取到用戶(hù)信息，需重試 | 請(qǐng)檢查用戶(hù)信息是否正確 |
| 272758286 | openid不正確 | 請(qǐng)檢查openid是否正確 |
| 272758293 | 簽名錯(cuò)誤 | 請(qǐng)檢查簽名是否正確 |
| 272758295，272758304 | 系統(tǒng)超時(shí)，請(qǐng)重試 | 請(qǐng)稍后重試 |
| 272756755 | 發(fā)券商戶(hù)號(hào)必須為制券商戶(hù)號(hào)或券歸屬商戶(hù)號(hào) | 請(qǐng)檢查發(fā)券商戶(hù)號(hào)是否為制券商戶(hù)號(hào)或券歸屬商戶(hù)號(hào) |
| 272756757 | 用戶(hù)openid對(duì)應(yīng)的appid必須與發(fā)券商戶(hù)號(hào)有綁定關(guān)系 | 請(qǐng)檢查用戶(hù)openid對(duì)應(yīng)的appid與發(fā)券商戶(hù)號(hào)是否有綁定關(guān)系 |
| 268435461 | H5領(lǐng)券域名參數(shù)錯(cuò)誤 | 每一個(gè)H5領(lǐng)券域名后，都需添加#wechat_redirect，請(qǐng)檢查是否添加 |
| 272756767 | 指定Code發(fā)券模式下， 沒(méi)有填寫(xiě)指定Code信息 | 請(qǐng)檢查發(fā)券參數(shù)，檢查是否有填寫(xiě)Coupon_code |
| 272757252 | 無(wú)權(quán)限操作 | 請(qǐng)檢查調(diào)用發(fā)券接口的發(fā)券商戶(hù)號(hào)與批次號(hào)之間的關(guān)系，是否未批次的創(chuàng)建方或歸屬方或有合作授權(quán)關(guān)系 |
| 272756761 | 上傳的Code已用完 | 發(fā)券批次的券Code模式是上傳自定義Code，請(qǐng)檢查上傳的Code是否充足 |