# 1. 接口規(guī)則
為了在保證支付安全的前提下，帶給商戶簡單、一致且易用的開發(fā)體驗(yàn)，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請參考APIv3接口規(guī)則。
# 2. 開發(fā)準(zhǔn)備
# 2.1. 搭建和配置開發(fā)環(huán)境
為了幫助開發(fā)者調(diào)用開放接口，我們提供了JAVA、PHP、GO三種語言版本的開發(fā)庫，封裝了簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語言版本的開發(fā)庫將在近期陸續(xù)提供）。
測試步驟：
1、根據(jù)自身開發(fā)語言，選擇對應(yīng)的開發(fā)庫并構(gòu)建項(xiàng)目，具體配置請參考下面鏈接的詳細(xì)說明：
- wechatpay-java (opens new window)（推薦）、wechatpay-apache-httpclient (opens new window)，適用于Java開發(fā)者。
- 注：當(dāng)前開發(fā)指引接口JAVA示例代碼采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推薦）、wechatpay-guzzle-middleware (opens new window)，適用于PHP開發(fā)者。
- 注：當(dāng)前開發(fā)指引接口PHP示例代碼采用wechatpay-guzzle-middleware版本。
- wechatpay-go (opens new window)，適用于Go開發(fā)者。
更多資源可前往微信支付開發(fā)者社區(qū) (opens new window)搜索查看。
2、創(chuàng)建加載商戶私鑰、加載平臺證書、初始化httpClient的通用方法。
3、基于接口的示例代碼，替換請求參數(shù)后可發(fā)起測試。
說明：
- 上面的開發(fā)庫為微信支付官方開發(fā)庫，其它沒有審核或者控制下的第三方工具和庫，微信支付不保證它們的安全性和可靠性。通過包管理工具引入SDK后，可根據(jù)下面每個接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測試。
- 開發(fā)者如果想詳細(xì)了解簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實(shí)現(xiàn)，可閱讀下面的詳細(xì)說明：
- 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
# 業(yè)務(wù)流程時序圖
重點(diǎn)步驟說明：
步驟5 商戶創(chuàng)建商家券后，可通過《創(chuàng)建全場滿額送活動》接口創(chuàng)建支付有禮活動，微信支付生成支付有禮活動并返回活動ID給到商戶。
步驟20 支付有禮活動創(chuàng)建后，商戶可通過《獲取活動詳情接口》查詢管理活動。
步驟22 活動創(chuàng)建后，如需結(jié)束活動，可通過《終止活動》接口，結(jié)束活動。
# 3.2. API接入（含示例代碼）
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入支付有禮，完成與微信支付對接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請商戶結(jié)合自身業(yè)務(wù)需求進(jìn)行評估、修改。
# 3.2.1. 【服務(wù)端】創(chuàng)建全場滿額送活動
步驟說明：商戶可以創(chuàng)建滿額送活動，用戶支付后送全場券，提升交易額。
background_color取值：
重要入?yún)⒄f明：
- activity_name：活動名稱。
- activity_second_title：活動副標(biāo)題。
- merchant_logo_url：商戶logo，送出優(yōu)惠券時展示， 僅支持通過《圖片上傳API》接口獲取的圖片URL地址。
- out_request_no：商戶請求單號，商戶創(chuàng)建批次憑據(jù)號（格式：商戶ID+日期+流水號），商戶側(cè)需保持唯一性，可包含英文字母，數(shù)字，｜，_，*，-等內(nèi)容，不允許出現(xiàn)其他不合法符號。
- delivery_purpose：投放目的。枚舉值：
OFF_LINE_PAY：拉用戶回店消費(fèi)
JUMP_MINI_APP：引導(dǎo)用戶前往小程序消費(fèi)。 - send_content：發(fā)放內(nèi)容，可選單張券或禮包，選禮包時獎品限定3-5個。枚舉值：
SINGLE_COUPON：單張券
GIFT_PACKAGE：禮包
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見創(chuàng)建全場滿額送活動接口文檔。
# 3.2.2. 【服務(wù)端】獲取活動詳情接口
步驟說明：商戶創(chuàng)建活動后，可以通過該接口查詢支付有禮的活動詳情，用于管理活動。
重要入?yún)⒄f明：
activity_id：活動ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見獲取活動詳情接口接口文檔。
# 3.2.3. 【服務(wù)端】獲取活動發(fā)券商戶號
步驟說明：商戶創(chuàng)建活動后，可以通過該接口查詢支付有禮的發(fā)券商戶號，用于管理活動。
重要入?yún)⒄f明：
- activity_id：活動ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見獲取活動發(fā)券商戶號接口文檔。
# 3.2.4. 【服務(wù)端】獲取活動指定商品列表
步驟說明：商戶創(chuàng)建活動后，可以通過該接口查詢支付有禮的活動指定商品，用于管理活動。
重要入?yún)⒄f明：
- activity_id：活動ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見獲取活動指定商品列表接口文檔。
# 3.2.5. 【服務(wù)端】終止活動
步驟說明：商戶可通過該接口停止支付有禮活動。
重要入?yún)⒄f明：
- activity_id：活動ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見終止活動接口文檔。
# 3.2.6. 【服務(wù)端】新增活動發(fā)券商戶號
步驟說明：商戶創(chuàng)建活動后，可以通過該接口增加支付有禮的發(fā)券商戶號，用于管理活動。
重要入?yún)⒄f明：
- activity_id：活動ID。
- add_request_no：請求業(yè)務(wù)單據(jù)號，商戶添加發(fā)券商戶號的憑據(jù)號，商戶側(cè)需保持唯一性。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見新增活動發(fā)券商戶號接口文檔。
# 3.2.7. 【服務(wù)端】獲取支付有禮活動列表
步驟說明：商戶根據(jù)一定過濾條件，查詢已創(chuàng)建的支付有禮活動。
重要入?yún)⒄f明：
- offset：分頁頁碼，頁面從0開始。
- limit：分頁大小。特殊規(guī)則：最大取值為100，最小為1。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見獲取支付有禮活動列表接口文檔。
# 3.2.8. 【服務(wù)端】刪除活動發(fā)券商戶號
步驟說明：商戶創(chuàng)建活動后，可以通過該接口刪除支付有禮的發(fā)券商戶號，用于管理活動。
重要入?yún)⒄f明：
- activity_id：活動ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見刪除活動發(fā)券商戶號接口文檔。
# 4. 常見問題
# Q：支付有禮創(chuàng)建全場滿額送活動API返回“發(fā)券商戶號校驗(yàn)失敗，請核實(shí)是否滿足同品牌等規(guī)則”
A：支付有禮活動的曝光商戶號必須是商家券歸屬商戶號的同品牌。同品牌商戶號是指同一企業(yè)/集團(tuán)/品牌/公司旗下，如果存在多個微信支付商戶號，該企業(yè)/集團(tuán)/品牌/公司可以授權(quán)財(cái)付通支付科技有限公司將其旗下的多個商戶號創(chuàng)建為同品牌商戶號組合。主要用于更便利使用免充值營銷產(chǎn)品功能，包括開通產(chǎn)品權(quán)限、配置組合內(nèi)商戶號為可用商戶、配置活動后可用商戶免審核等。
# Q：支付有禮創(chuàng)建全場滿額送活動API返回“商家券信息不滿足活動規(guī)則，請核實(shí)券有效期或code”
A：支付有禮中投放批次的校驗(yàn)，請按照以下幾點(diǎn)排查：
- 單張券/券包中所有的券開始時間需早于支付有禮活動的開始時間，結(jié)束時間需晚于支付有禮的結(jié)束時間。
- 如果批次為上傳code模式，需先上傳code再投放到支付有禮。
- 添加券包時，庫存、限領(lǐng)和歸屬商戶號需要保持一致。
- 曝光商戶號、批次的歸屬商戶號需要全部為同品牌。
# Q：支付有禮創(chuàng)建全場滿額送活動API，開始時間和結(jié)束時間描述的“最長可以配置1年內(nèi)的活動”中的“1年”如何計(jì)算？
A：間隔需要小于31536000s，即需要小于365天。
# Q：支付有禮創(chuàng)建全場滿額送活動API上傳了merchant_id_list字段，接著調(diào)用了獲取支付有禮活動列表API，并沒有merchant_id_list返回，該字段在什么情況下才返回？
A：查詢活動發(fā)券商戶號API才會有這個字段返回，接口文檔地址。
# Q：支付有禮發(fā)放商家券，用戶領(lǐng)券沒有收到領(lǐng)券事件通知OpenID
A：請檢查對應(yīng)的批次，調(diào)用創(chuàng)建商家券接口時是否有設(shè)置事件通知AppID參數(shù)（notify_appid）。
# Q：配置使用「立即使用」跳轉(zhuǎn)商家小程序的能力時，有什么需要注意的地方？
A：在小程序支付場景下，當(dāng)用戶從支付有禮活動落地頁點(diǎn)擊「立即使用」跳轉(zhuǎn)至商家小程序時，建議不處理小程序調(diào)起支付的回調(diào)結(jié)果。
