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