# 1. 接口規(guī)則
為了在保證支付安全的前提下，帶給商戶簡(jiǎn)單、一致且易用的開(kāi)發(fā)體驗(yàn)，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請(qǐng)參考APIv3接口規(guī)則。
# 2. 開(kāi)發(fā)準(zhǔn)備
# 2.1. 搭建和配置開(kāi)發(fā)環(huán)境
為了幫助開(kāi)發(fā)者調(diào)用開(kāi)放接口，我們提供了JAVA、PHP、GO三種語(yǔ)言版本的開(kāi)發(fā)庫(kù)，封裝了簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語(yǔ)言版本的開(kāi)發(fā)庫(kù)將在近期陸續(xù)提供）。
測(cè)試步驟：
1、根據(jù)自身開(kāi)發(fā)語(yǔ)言，選擇對(duì)應(yīng)的開(kāi)發(fā)庫(kù)并構(gòu)建項(xiàng)目，具體配置請(qǐng)參考下面鏈接的詳細(xì)說(shuō)明：
- wechatpay-java (opens new window)（推薦）、wechatpay-apache-httpclient (opens new window)，適用于Java開(kāi)發(fā)者。
- 注：當(dāng)前開(kāi)發(fā)指引接口JAVA示例代碼采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推薦）、wechatpay-guzzle-middleware (opens new window)，適用于PHP開(kāi)發(fā)者。
- 注：當(dāng)前開(kāi)發(fā)指引接口PHP示例代碼采用wechatpay-guzzle-middleware版本。
- wechatpay-go (opens new window)，適用于Go開(kāi)發(fā)者。
更多資源可前往微信支付開(kāi)發(fā)者社區(qū) (opens new window)搜索查看。
2、創(chuàng)建加載商戶私鑰、加載平臺(tái)證書(shū)、初始化httpClient的通用方法。
3、基于接口的示例代碼，替換請(qǐng)求參數(shù)后可發(fā)起測(cè)試。
說(shuō)明：
- 上面的開(kāi)發(fā)庫(kù)為微信支付官方開(kāi)發(fā)庫(kù)，其它沒(méi)有審核或者控制下的第三方工具和庫(kù)，微信支付不保證它們的安全性和可靠性。通過(guò)包管理工具引入SDK后，可根據(jù)下面每個(gè)接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測(cè)試。
- 開(kāi)發(fā)者如果想詳細(xì)了解簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實(shí)現(xiàn)，可閱讀下面的詳細(xì)說(shuō)明：
- 簽名生成
- 簽名驗(yàn)證
- 敏感信息加解密
- merchantPrivateKey（私鑰）
- wechatpayCertificates（平臺(tái)證書(shū)）
- APIV3Key（V3 key）
- 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。
# 2.2. 業(yè)務(wù)開(kāi)發(fā)配置
# 2.2.1. 開(kāi)通營(yíng)銷(xiāo)事件推送能力
開(kāi)通營(yíng)銷(xiāo)事件推送能力說(shuō)明：
- 用于設(shè)置接收商家券相關(guān)事件通知的URL，可接收商家券相關(guān)的事件通知、包括發(fā)放通知等。需要設(shè)置接收通知的URL，并在商戶平臺(tái)開(kāi)通營(yíng)銷(xiāo)事件推送的能力，即可接收到相關(guān)通知。
- 營(yíng)銷(xiāo)事件推送：點(diǎn)擊開(kāi)通產(chǎn)品權(quán)限。 由商家券批次創(chuàng)建方登錄Pay平臺(tái)，操作開(kāi)通
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
# 業(yè)務(wù)流程時(shí)序圖
重點(diǎn)步驟說(shuō)明：
步驟1 商戶發(fā)起創(chuàng)建商家券請(qǐng)求，可通過(guò)《創(chuàng)建商家券》接口創(chuàng)建商家券，微信支付生成商家券批次后并返回商家券批次號(hào)給到商戶。
請(qǐng)求參數(shù)商戶logo（merchant_url）的內(nèi)容要求使用圖片上傳（營(yíng)銷(xiāo)專(zhuān)用）接口上傳后獲取
步驟4.2 商戶獲取到商家券批次號(hào)，需要調(diào)用《小程序發(fā)券插件》來(lái)發(fā)放商戶券，并獲取微信支付返回商家券發(fā)放結(jié)果。
步驟7.2 商戶發(fā)券成功后，商戶可通過(guò)《查詢商家券批次詳情》、《根據(jù)過(guò)濾條件查詢用戶的券》、《查詢用戶券詳情》等商家券管理接口進(jìn)行券管理，商戶需核銷(xiāo)用戶券時(shí)，可通過(guò)調(diào)用《核銷(xiāo)用戶的券》來(lái)核銷(xiāo)用戶微信卡包中具體某一張商家券。
# 3.2. API接入（含示例代碼）
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入商家券產(chǎn)品，完成與微信支付對(duì)接的部分。
注意
- 文檔中的代碼示例是用來(lái)闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號(hào)及請(qǐng)求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請(qǐng)商戶結(jié)合自身業(yè)務(wù)需求進(jìn)行評(píng)估、修改。
# 3.2.1. 【服務(wù)端】創(chuàng)建商家券
步驟說(shuō)明： 通過(guò)此接口可為有需求的商戶創(chuàng)建商家券。當(dāng)前支持創(chuàng)建的商家券類(lèi)型包含滿減券、換購(gòu)券和折扣券三種。
卡券背景顏色圖：
商家券樣式圖：
券詳情信息展示：
重要入?yún)⒄f(shuō)明：
- belong_merchant： 批次歸屬商戶號(hào)，批次歸屬于哪個(gè)商戶。普通商戶請(qǐng)?zhí)顚?xiě)普通商戶號(hào)。
- out_request_no： 商戶請(qǐng)求單號(hào)，商戶創(chuàng)建批次憑據(jù)號(hào)（格式：商戶ID+日期+流水號(hào)），商戶側(cè)需保持唯一性。
- max_coupons： 批次最大發(fā)放個(gè)數(shù)，批次最大可發(fā)放個(gè)數(shù)限制。特殊規(guī)則：取值范圍 1 ≤ value ≤ 1000000000。
- notify_appid： 事件通知AppID，用于回調(diào)通知時(shí)，計(jì)算返回操作用戶的OpenID（諸如領(lǐng)券用戶），支持小程序or公眾號(hào)的AppID；如該字段不填寫(xiě)，則回調(diào)通知中涉及到用戶身份信息的OpenID與unionid都將為空。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)創(chuàng)建商家券接口文檔。
# 3.2.2. 【服務(wù)端】查詢商家券批次詳情
步驟說(shuō)明： 商戶可通過(guò)該接口查詢已創(chuàng)建的商家券批次詳情信息。
卡券背景顏色圖：
重要入?yún)⒄f(shuō)明：
- stock_id： 批次號(hào)，微信為每個(gè)商家券批次分配的唯一ID。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)查詢商家券批次詳情接口文檔。
# 3.2.3. 【服務(wù)端】核銷(xiāo)用戶的券
步驟說(shuō)明： 在用戶滿足優(yōu)惠門(mén)檻后，商戶可通過(guò)該接口核銷(xiāo)用戶微信卡包中具體某一張商家券。
重要入?yún)⒄f(shuō)明：
- coupon_code： 券code，券的唯一標(biāo)識(shí)。
- AppID： 公眾賬號(hào)ID，支持傳入與當(dāng)前調(diào)用接口商戶號(hào)有綁定關(guān)系的AppID。支持小程序AppID與公眾號(hào)AppID。核銷(xiāo)接口返回的OpenID會(huì)在該傳入AppID下進(jìn)行計(jì)算獲得。
- use_request_no： 核銷(xiāo)請(qǐng)求單據(jù)號(hào)，每次核銷(xiāo)請(qǐng)求的唯一標(biāo)識(shí)，商戶需保證唯一。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)核銷(xiāo)用戶的券接口文檔。
# 3.2.4. 【服務(wù)端】根據(jù)過(guò)濾條件查詢用戶券
步驟說(shuō)明： 商戶自定義篩選條件（如創(chuàng)建商戶號(hào)、歸屬商戶號(hào)、發(fā)放商戶號(hào)等），查詢指定微信用戶卡包中滿足對(duì)應(yīng)條件的所有商家券信息。
重要入?yún)⒄f(shuō)明：
- OpenID： 用戶標(biāo)識(shí)，OpenID信息，用戶在AppID下的唯一標(biāo)識(shí)。
- AppID： 公眾賬號(hào)ID，支持傳入與當(dāng)前調(diào)用接口商戶號(hào)有綁定關(guān)系的AppID。支持小程序AppID與公眾號(hào)AppID。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)根據(jù)過(guò)濾條件查詢用戶的券接口文檔。
# 3.2.5. 【服務(wù)端】查詢用戶券詳情
步驟說(shuō)明： 商戶可通過(guò)該接口查詢微信用戶卡包中某一張商家券的詳情信息。
重要入?yún)⒄f(shuō)明：
- coupon_code： 券code，券的唯一標(biāo)識(shí)。
- OpenID： 用戶標(biāo)識(shí)，OpenID信息，用戶在AppID下的唯一標(biāo)識(shí)。
- AppID： 公眾賬號(hào)ID，支持傳入與當(dāng)前調(diào)用接口商戶號(hào)有綁定關(guān)系的AppID。支持小程序AppID與公眾號(hào)AppID。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)查詢用戶券詳情接口文檔。
# 3.2.6. 【服務(wù)端】上傳預(yù)存code
步驟說(shuō)明： 商家券的Code碼可由微信后臺(tái)隨機(jī)分配，同時(shí)支持商戶自定義。如商家已有自己的優(yōu)惠券系統(tǒng)，可直接使用自定義模式。即商家預(yù)先向微信支付上傳券Code，當(dāng)券在發(fā)放時(shí)，微信支付自動(dòng)從已導(dǎo)入的Code中隨機(jī)取值（不能指定），派發(fā)給用戶。
重要入?yún)⒄f(shuō)明：
- stock_id： 批次號(hào)，微信為每個(gè)商家券批次分配的唯一ID。
- upload_request_no： 請(qǐng)求業(yè)務(wù)單據(jù)號(hào)，商戶上傳code的憑據(jù)號(hào)，商戶側(cè)需保持唯一性。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)上傳預(yù)存code接口文檔。
# 3.2.7. 【服務(wù)端】設(shè)置商家券事件通知地址
步驟說(shuō)明： 用于設(shè)置接收商家券相關(guān)事件通知的URL，可接收商家券相關(guān)的事件通知、包括發(fā)放通知等。需要設(shè)置接收通知的URL，并在商戶平臺(tái)開(kāi)通營(yíng)銷(xiāo)事件推送的能力，即可接收到相關(guān)通知。
注意
- 僅可以收到由商戶自己創(chuàng)建的批次相關(guān)的通知。
- 需要設(shè)置APIv3密鑰，否則無(wú)法收到回調(diào)。
- 如果需要領(lǐng)券回調(diào)中的參數(shù)OpenID。需要?jiǎng)?chuàng)券時(shí)候傳入notify_appid參數(shù)。
重要入?yún)⒄f(shuō)明：
- notify_url： 通知URL地址，商戶提供的用于接收商家券事件通知的URL地址，必須支持HTTPS。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)設(shè)置商家券事件通知地址接口文檔。
# 3.2.8. 【服務(wù)端】查詢商家券事件通知地址
步驟說(shuō)明： 通過(guò)調(diào)用此接口可查詢?cè)O(shè)置的通知URL。
注意
- 僅可以查詢由請(qǐng)求商戶號(hào)設(shè)置的商家券通知URL
重要入?yún)⒄f(shuō)明：
- mchid： 商戶號(hào)，微信支付商戶的商戶號(hào)，由微信支付生成并下發(fā)，不填默認(rèn)查詢調(diào)用方商戶的通知URL。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)查詢商家券事件通知地址接口文檔。
# 3.2.9. 【服務(wù)端】關(guān)聯(lián)訂單信息
步驟說(shuō)明： 將有效態(tài)（未核銷(xiāo)）的商家券與訂單信息關(guān)聯(lián)，用于后續(xù)參與搖獎(jiǎng)&返傭激勵(lì)等操作的統(tǒng)計(jì)。
注意
- 僅對(duì)有關(guān)聯(lián)訂單需求的券進(jìn)行該操作
重要入?yún)⒄f(shuō)明：
- stock_id： 批次號(hào)，微信為每個(gè)商家券批次分配的唯一ID。
- coupon_code： 券code，券的唯一標(biāo)識(shí)。
- out_trade_no： 關(guān)聯(lián)的商戶訂單號(hào)，微信支付下單時(shí)的商戶訂單號(hào)，預(yù)與該商家券關(guān)聯(lián)的微信支付。
- out_request_no： 商戶請(qǐng)求單號(hào)，商戶創(chuàng)建批次憑據(jù)號(hào)（格式：商戶ID+日期+流水號(hào)），商戶側(cè)需保持唯一性，可包含英文字母，數(shù)字，｜，_，*，-等內(nèi)容，不允許出現(xiàn)其他不合法符號(hào)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)關(guān)聯(lián)訂單信息接口文檔。
# 3.2.10. 【服務(wù)端】取消關(guān)聯(lián)訂單信息
步驟說(shuō)明： 取消商家券與訂單信息的關(guān)聯(lián)關(guān)系。
注意
- 建議取消前調(diào)用查詢接口，查到當(dāng)前關(guān)聯(lián)的商戶單號(hào)并確認(rèn)后，再進(jìn)行取消操作。
重要入?yún)⒄f(shuō)明：
- stock_id： 批次號(hào)，微信為每個(gè)商家券批次分配的唯一ID。
- coupon_code： 券code，券的唯一標(biāo)識(shí)。
- out_trade_no： 關(guān)聯(lián)的商戶訂單號(hào)，微信支付下單時(shí)的商戶訂單號(hào)，預(yù)與該商家券關(guān)聯(lián)的微信支付。
- out_request_no： 商戶請(qǐng)求單號(hào)，商戶創(chuàng)建批次憑據(jù)號(hào)（格式：商戶ID+日期+流水號(hào)），商戶側(cè)需保持唯一性，可包含英文字母，數(shù)字，｜，_，*，-等內(nèi)容，不允許出現(xiàn)其他不合法符號(hào)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)取消關(guān)聯(lián)訂單信息接口文檔。
# 3.2.11. 【服務(wù)端】修改批次預(yù)算
步驟說(shuō)明： 商戶可以通過(guò)該接口修改批次單天發(fā)放上限數(shù)量或者批次最大發(fā)放數(shù)量。
重要入?yún)⒄f(shuō)明：
- stock_id： 批次號(hào)，微信為每個(gè)商家券批次分配的唯一ID。
- modify_budget_request_no： 修改預(yù)算請(qǐng)求單據(jù)號(hào)（格式：商戶ID+日期+流水號(hào)），商戶側(cè)需保持唯一性。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)修改批次預(yù)算接口文檔。
# 3.2.12. 【服務(wù)端】修改商家券基本信息
步驟說(shuō)明： 商戶可以通過(guò)該接口修改商家券基本信息。
重要入?yún)⒄f(shuō)明：
- stock_id： 批次號(hào)，微信為每個(gè)商家券批次分配的唯一ID。
- out_request_no： 商戶請(qǐng)求單號(hào)，商戶修改批次憑據(jù)號(hào)（格式：商戶ID+日期+流水號(hào)），商戶側(cè)需保持唯一性。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)修改商家券基本信息接口文檔。
# 3.2.13. 【服務(wù)端】申請(qǐng)退券
步驟說(shuō)明： 商戶可以通過(guò)該接口為已核銷(xiāo)的券申請(qǐng)退券。
重要入?yún)⒄f(shuō)明：
- stock_id： 批次號(hào)，微信為每個(gè)商家券批次分配的唯一ID
- coupon_code： 券code，券的唯一標(biāo)識(shí)。
- return_request_no： 退券請(qǐng)求單據(jù)號(hào)，每次退券請(qǐng)求的唯一標(biāo)識(shí)，商戶需保證唯一。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)申請(qǐng)退券接口文檔。
# 3.2.14. 【服務(wù)端】使券失效
步驟說(shuō)明： 商戶可通過(guò)該接口將單張領(lǐng)取后未核銷(xiāo)的券進(jìn)行失效處理。
重要入?yún)⒄f(shuō)明：
- stock_id： 批次號(hào)，微信為每個(gè)商家券批次分配的唯一ID。
- coupon_code： 券code，券的唯一標(biāo)識(shí)。
- deactivate_request_no： 失效請(qǐng)求單據(jù)號(hào)，每次失效請(qǐng)求的唯一標(biāo)識(shí)，商戶需保證唯一。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)使券失效接口文檔。
# 3.2.15.【服務(wù)端】領(lǐng)券事件回調(diào)通知
步驟說(shuō)明： 領(lǐng)券完成后，微信會(huì)把相關(guān)領(lǐng)券結(jié)果和用戶信息發(fā)送給商戶，商戶需要接收處理，并按照文檔規(guī)范返回應(yīng)答。出于安全的考慮，我們對(duì)支付結(jié)果數(shù)據(jù)進(jìn)行了加密，商戶需要先對(duì)通知數(shù)據(jù)進(jìn)行解密，才能得到支付結(jié)果數(shù)據(jù)。
注意
- 領(lǐng)券事件通知是以POST 方法訪問(wèn)商戶設(shè)置的通知URL，通知的數(shù)據(jù)以JSON 格式通過(guò)請(qǐng)求主體（BODY）傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情。
- 加密不能保證通知請(qǐng)求來(lái)自微信。微信會(huì)對(duì)發(fā)送給商戶的通知進(jìn)行簽名，并將簽名值放在通知的HTTP頭Wechatpay-Signature。商戶應(yīng)當(dāng)驗(yàn)證簽名，以確認(rèn)請(qǐng)求來(lái)自微信，而不是其他的第三方。簽名驗(yàn)證的算法請(qǐng)參考 《微信支付API v3簽名驗(yàn)證》。
- 支付通知HTTP應(yīng)答碼為200或204才會(huì)當(dāng)作正常接收，當(dāng)回調(diào)處理異常時(shí)，應(yīng)答的HTTP狀態(tài)碼應(yīng)為500，或者4xx。
- 商戶成功接收到回調(diào)通知后應(yīng)返回成功的HTTP應(yīng)答碼為200或204。
- 同樣的通知可能會(huì)多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。 推薦的做法是，當(dāng)商戶系統(tǒng)收到通知進(jìn)行處理時(shí)，先檢查對(duì)應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，并判斷該通知是否已經(jīng)處理。如果未處理，則再進(jìn)行處理；如果已處理，則直接返回結(jié)果成功。在對(duì)業(yè)務(wù)數(shù)據(jù)進(jìn)行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進(jìn)行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂。
- 對(duì)后臺(tái)通知交互時(shí)，如果微信收到應(yīng)答不是成功或超時(shí)，微信認(rèn)為通知失敗，微信會(huì)通過(guò)一定的策略定期重新發(fā)起通知，盡可能提高通知的成功率，但微信不保證通知最終能成功。（通知頻率為60s/次 - 總計(jì)11次 ）
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 領(lǐng)券事件回調(diào)通知接口文檔。
# 4. 常見(jiàn)問(wèn)題
# Q：調(diào)用創(chuàng)建商家券接口返回“非法敏感圖片”
A：請(qǐng)求參數(shù)商戶logo（merchant_url）的內(nèi)容要求使用圖片上傳（營(yíng)銷(xiāo)專(zhuān)用）接口上傳后獲取，請(qǐng)檢查確認(rèn)。
# Q：創(chuàng)建商家券接口，goods_name字段展示在哪里？
A：展示在商家券詳情里面的優(yōu)惠說(shuō)明中。
# Q：調(diào)用修改商家券基本信息API返回：無(wú)法將輸入源“/body/stock_id”映射到目標(biāo)字段“批次號(hào)”中，此字段并非多重字段但被輸入源“/uri_template/stock_id”映射過(guò)了
A：請(qǐng)注意參數(shù)stock_id傳到請(qǐng)求URL里面，body里面就不用傳該參數(shù)。
# Q：商家券領(lǐng)券回調(diào)，正常設(shè)置地址，為什么接收不到回調(diào)信息？
A：請(qǐng)按以下幾點(diǎn)檢查
- 請(qǐng)檢查是否有正確設(shè)置APIv3。設(shè)置步驟如下： 【微信商戶平臺(tái)—>賬戶設(shè)置—>API安全—>設(shè)置APIv3】
- 請(qǐng)檢查回調(diào)URL是否能正常公網(wǎng)訪問(wèn)
- 如果是HTTP地址，建議更換支持HTTPS
- 是否開(kāi)啟了防火墻，如果開(kāi)戶了防火墻，請(qǐng)?zhí)砑游⑿胖Ц稜I(yíng)銷(xiāo)回調(diào)IP：
- 上海電信出口網(wǎng)段 101.226.103.0/2
- 上海聯(lián)通出口網(wǎng)段 140.207.54.0/25
- 上海CAP出口網(wǎng)段 121.51.58.128/25
# Q：商家券消費(fèi)門(mén)檻字段transaction_minimum不填寫(xiě)為什么會(huì)報(bào)錯(cuò)？
A：該字段屬于必填字段，可以填寫(xiě)為0。
