最新更新時間:2021.05.19 版本說明
微信支付為商戶提供H5發(fā)券接口,可在H5頁面為指定用戶發(fā)放指定批次的微信支付商家券。推薦使用 JSAPI H5發(fā)券功能,兩者區(qū)別如下:
1. JSAPI H5發(fā)券功能 發(fā)券后會回調(diào)領(lǐng)券結(jié)果給到商家,方便商家做對應(yīng)的處理;該H5發(fā)券不回調(diào)信息給商家,依賴商家主動去查詢。
2. 支持小程序嵌套H5場景的發(fā)券,該H5發(fā)券不支持在小程序內(nèi)進行調(diào)用。
原理:H5發(fā)券的領(lǐng)券頁面是帶有weixin域名的一個H5頁面,不支持在商家小程序調(diào)用(因為商家沒有這個域名的備案資質(zhì));而jsapi發(fā)券的領(lǐng)券頁面是原生頁面,不受小程序框架約束。
用戶在商戶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_redirect,否則會報錯,返回268435461錯誤碼
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
商戶需在Url中攜帶用戶信息及批次信息方可正常發(fā)券,具體參數(shù)如下:
參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
---|---|---|---|---|
批次號 | stock_id | string[1,20] | 是 | 微信支付商家券批次號 |
發(fā)券憑證 | out_request_no | string[1,128] | 是 | 發(fā)券憑證(示例格式:商戶 id+日期+流水號),可包含英文字母、數(shù)字,不允許出現(xiàn)其他不合法符號,商戶側(cè)需保證發(fā)放憑據(jù)號唯一性 |
簽名 | sign | string | 是 | 簽名計算值。 簽名方式:HMAC-SHA256。 簽名規(guī)則:詳見《V2 簽名規(guī)則》 參與簽名字段說明 注意:為了安全,簽名必須在后臺服務(wù)器計算,禁止在H5中計算,簽名 key 為微信支付 apiv2 的 signkey 示例值:9A0A8659F005D6984697E2CA0A9CF3B79A0A8659F005D6984697E2CA0A9CF3B7 |
發(fā)券商戶號 | send_coupon_merchant | string[8,15] | 是 | 調(diào)用發(fā)券接口的商戶號 |
用戶openid | open_id | string[1,128] | 是 | 目標發(fā)券的用戶openid 校驗規(guī)則: 1,可用歸屬商戶號綁定的APPID獲取的openid 2,可用發(fā)券商戶綁定的APPID獲取的openid 獲取openid請查看文檔 |
自定義領(lǐng)取時間 | customize_send_time{n} | string[1,32] | 否 | 商家券在商戶業(yè)務(wù)系統(tǒng)里的實際領(lǐng)取時間,僅針對有設(shè)置相對領(lǐng)取時間的批次生效(即批次有設(shè)置“生效后N天內(nèi)有效”或“領(lǐng)取后N天開始生效”時間字段)。傳入后,將使用傳入的時間點,做為商家券領(lǐng)取時間來計算有效期,而非用戶在微信支付系統(tǒng)中點擊領(lǐng)取的時間。 遵循rfc3339標準格式,格式為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秒。 注:該字段未啟用 示例值:2015-05-20T13:29:35+08:00 |
券 code | coupon_code | string[1,128] | 否 | 如果批次配置了 code 模式為“商戶發(fā)放時接口指定券 code”,則必填,其他模式無需填寫 示例值:75345199 |
參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
---|---|---|---|---|
批次號 | stock_id | string[1,20] | 是 | 微信支付券批次id 示例值:123 |
發(fā)券憑證 | out_request_no | string[1,128] | 是 | 發(fā)券憑證,
可包含英文字母,數(shù)字,|,_,*,-等內(nèi)容,不允許出現(xiàn)其他不合法符號,需在單個批次單個用戶下確保唯一性 示例值:1234567 |
發(fā)券商戶號 | send_coupon_merchant | string[8,15] | 是 | 調(diào)用發(fā)券接口的商戶號 示例值:10016226 |
用戶openid | open_id | string[1,128] | 是 | 目標發(fā)券的用戶openid 示例值:10011212261 |
券 code | coupon_code | string[1,128] | 否 | 如果批次配置了 code 模式為“商戶發(fā)放時接口指定券 code”,則必填,其他模式無需填寫 示例值:75345199 |
coupon_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ā)券模式下, 當前發(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_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是否充足 |