# 1. 接口規(guī)則
為了在保證支付安全的前提下，帶給商戶簡單、一致且易用的開發(fā)體驗，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請參考APIv3接口規(guī)則。
# 2. 開發(fā)準(zhǔn)備
# 2.1. 搭建和配置開發(fā)環(huán)境
為了幫助開發(fā)者調(diào)用開放接口，我們提供了JAVA、PHP、GO三種語言版本的開發(fā)庫，封裝了簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語言版本的開發(fā)庫將在近期陸續(xù)提供）。
測試步驟：
1、根據(jù)自身開發(fā)語言，選擇對應(yīng)的開發(fā)庫并構(gòu)建項目，具體配置請參考下面鏈接的詳細(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ì)了解簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實現(xiàn)，可閱讀下面的詳細(xì)說明：
- 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
# 業(yè)務(wù)流程時序圖
重點步驟說明：
步驟2 創(chuàng)建代金券：商戶可通過《創(chuàng)建代金券批次》接口創(chuàng)建代金券，微信支付生成代金券批次后并返回代金券批次號給到商戶。
步驟7 激活代金券：商戶獲取到代金券批次號，需要確認(rèn)并激活代金券，該批次代金券才能發(fā)放，需要調(diào)用《激活代金券批次》接口來激活創(chuàng)建的代金券。
步驟12 發(fā)放代金券：已經(jīng)激活的代金券，商戶可調(diào)用微信支付《發(fā)放指定批次的代金券》接口來進(jìn)行代金券發(fā)放，并獲取微信支付返回代金券發(fā)放結(jié)果。
步驟17 管理代金券：商戶發(fā)券成功后，商戶可通過《查詢批次詳情》、《查詢代金券詳情》等代金券管理接口進(jìn)行券管理。
# 3.2. API接入（含示例代碼）
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入支付有禮，完成與微信支付對接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請商戶結(jié)合自身業(yè)務(wù)需求進(jìn)行評估、修改。
# 3.2.1. 【服務(wù)端】創(chuàng)建代金券批次
步驟說明： 通過創(chuàng)建代金券批次接口，可創(chuàng)建代金券的類型包含預(yù)充值和免充值兩種類型。
- 預(yù)充值代金券適用于第三方出資策劃的活動，例如：滿100減10. 指訂單金額100元，用戶實付90元，商戶實收100元。
- 免充值適用于商戶策劃的活動，例如：滿100減10。 指訂單金額100元，用戶實付90元（用戶領(lǐng)券后，在支付中直接核銷10元），商戶實收90元。
background_color取值：
重要入?yún)⒄f明：
- out_trade_no： 商戶創(chuàng)建批次憑據(jù)號（格式：商戶ID+日期+流水號），可包含英文字母，數(shù)字，|，_，*，-等內(nèi)容，不允許出現(xiàn)其他不合法符號，商戶側(cè)需保持商戶單據(jù)號全局唯一
- available_begin_time： 批次開始時間
- 開始時間不可早于當(dāng)前時間
- 不能創(chuàng)建365天后開始的批次
- 批次可用時間范圍最長為90天
- stock_name： 批次名稱
校驗規(guī)則：
- 批次名稱最多9個中文漢字
- 批次名稱最多20個字母
- 批次名稱中不能包含不當(dāng)內(nèi)容和特殊字符 _ , ; |
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見創(chuàng)建代金券批次接口文檔
# 3.2.2. 【服務(wù)端】激活代金券批次
步驟說明： 制券成功后，通過調(diào)用激活接口激活代金券批次。
- 說明： 如果是預(yù)充值代金券，激活時從商戶賬戶余額中鎖定本批次的營銷資金。
重要入?yún)⒄f明：
- stock_creator_mchid： 批次創(chuàng)建方商戶號
- stock_id： 微信為每個代金券批次分配的唯一ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見激活代金券批次接口文檔
# 3.2.3. 【服務(wù)端】發(fā)放代金券批次
步驟說明： 商戶平臺/API完成制券后，可使用發(fā)放代金券接口發(fā)券。通過調(diào)用此接口可發(fā)放指定批次給指定用戶，發(fā)券場景可以是小程序、H5、App等。
重要入?yún)⒄f明：
- out_trade_no： 商戶系統(tǒng)內(nèi)部訂單號，只能是數(shù)字、大小寫字母_-*且在同一個商戶號下唯一
- OpenID： OpenID是微信用戶在AppID下的唯一用戶標(biāo)識（AppID不同，則獲取到的OpenID就不同），可用于永久標(biāo)記一個用戶。OpenID獲取方式請參考以下文檔小程序獲取OpenID (opens new window)、公眾號獲取OpenID (opens new window)、App獲取OpenID (opens new window)
- stock_creator_mchid： 批次創(chuàng)建方商戶號
- stock_id： 微信為每個代金券批次分配的唯一ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見發(fā)放指定批次的代金券接口文檔。
# 3.2.4. 【服務(wù)端】暫停代金券批次
步驟說明： 通過此接口可暫停指定代金券批次。暫停后，該代金券批次暫停發(fā)放，用戶無法通過任何渠道再領(lǐng)取該批次的券。暫停接口的前提是批次處于激活狀態(tài)。
重要入?yún)⒄f明：
- stock_creator_mchid： 批次創(chuàng)建方商戶號
- stock_id： 微信為每個代金券批次分配的唯一ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見暫停代金券批次接口文檔
# 3.2.5. 【服務(wù)端】重啟代金券批次
步驟說明： 通過此接口可重啟指定代金券批次。重啟后，該代金券批次可以再次發(fā)放。重啟接口的前提是批次處于暫停狀態(tài)。
重要入?yún)⒄f明：
- stock_creator_mchid： 批次創(chuàng)建方商戶號
- stock_id： 微信為每個代金券批次分配的唯一ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見重啟代金券批次接口文檔
# 3.2.6. 【服務(wù)端】條件查詢批次列表
步驟說明： 通過此接口可查詢多個批次的信息，包括批次的配置信息以及批次概況數(shù)據(jù)。
重要入?yún)⒄f明：
- stock_creator_mchid： 批次創(chuàng)建方商戶號
- status： 批次狀態(tài)
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見條件查詢批次列表接口文檔
# 3.2.7. 【服務(wù)端】查詢批次詳情
步驟說明： 通過此接口可查詢批次信息，包括批次的配置信息以及批次概況數(shù)據(jù)。
重要入?yún)⒄f明：
- stock_creator_mchid： 批次創(chuàng)建方商戶號
- stock_id： 微信為每個代金券批次分配的唯一ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢批次詳情接口文檔
# 3.2.8. 【服務(wù)端】查詢代金券詳情
步驟說明： 通過此接口可查詢代金券信息，包括代金券的基礎(chǔ)信息、狀態(tài)。如代金券已核銷，會包括代金券核銷的訂單信息（訂單號、單品信息等）。
重要入?yún)⒄f明：
- OpenID： OpenID是微信用戶在AppID下的唯一用戶標(biāo)識（AppID不同，則獲取到的OpenID就不同），可用于永久標(biāo)記一個用戶。OpenID獲取方式請參考以下文檔小程序獲取OpenID (opens new window)、公眾號獲取OpenID (opens new window)、App獲取OpenID (opens new window)
- coupon_id： 微信為代金券唯一分配的ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢代金券詳情接口文檔
# 3.2.9. 【服務(wù)端】查詢代金券可用商戶
步驟說明： 通過調(diào)用此接口可查詢批次的可用商戶號，判斷券是否在某商戶號可用，來決定是否展示。
重要入?yún)⒄f明：
- stock_creator_mchid： 批次創(chuàng)建方商戶號
- stock_id： 微信為每個代金券批次分配的唯一ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢代金券可用商戶接口文檔
# 3.2.10. 【服務(wù)端】查詢代金券可用單品
步驟說明： 通過此接口可查詢批次的可用商品編碼，判斷券是否可用于某些商品，來決定是否展示。
重要入?yún)⒄f明：
- stock_creator_mchid： 批次創(chuàng)建方商戶號
- stock_id： 微信為每個代金券批次分配的唯一ID
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢代金券可用單品接口文檔
# 3.2.11. 【服務(wù)端】根據(jù)商戶號查用戶的券
步驟說明： 可通過該接口查詢用戶在某商戶號可用的全部券，可用于商戶的小程序/H5中，用戶"我的代金券"或"提交訂單頁"展示優(yōu)惠信息。無法查詢到微信支付立減金。本接口查不到用戶的微信支付立減金（又稱“全平臺通用券”），即在所有商戶都可以使用的券，例如：搖搖樂紅包；當(dāng)按可用商戶號查詢時，無法查詢用戶已經(jīng)核銷的券。
重要入?yún)⒄f明：
- stock_creator_mchid： 批次創(chuàng)建方商戶號
- stock_id： 微信為每個代金券批次分配的唯一ID。
- OpenID： OpenID是微信用戶在AppID下的唯一用戶標(biāo)識（AppID不同，則獲取到的OpenID就不同），可用于永久標(biāo)記一個用戶。OpenID獲取方式請參考以下文檔小程序獲取OpenID (opens new window)、公眾號獲取OpenID (opens new window)、App獲取OpenID (opens new window)
- coupon_id： 微信為代金券唯一分配的ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見根據(jù)商戶號查用戶的券接口文檔
# 3.2.12. 【服務(wù)端】下載批次核銷明細(xì)
步驟說明： 可獲取到某批次的核銷明細(xì)數(shù)據(jù)，包括訂單號、單品信息、銀行流水號等，用于對賬/數(shù)據(jù)分析。
重要入?yún)⒄f明：
- stock_id： 微信為每個代金券批次分配的唯一ID
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見下載批次核銷明細(xì)接口文檔
# 3.2.13. 【服務(wù)端】下載批次退款明細(xì)
步驟說明： 可獲取到某批次的退款明細(xì)數(shù)據(jù)，包括訂單號、單品信息、銀行流水號等，用于對賬/數(shù)據(jù)分析。
重要入?yún)⒄f明：
- stock_id： 微信為每個代金券批次分配的唯一ID。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見下載批次退款明細(xì)接口文檔
# 3.2.14. 【服務(wù)端】設(shè)置消息通知地址
步驟說明： 用于設(shè)置接收營銷事件通知的URL，可接收營銷相關(guān)的事件通知，包括核銷、發(fā)放、退款等。
重要入?yún)⒄f明：
- notify_url： 必須為HTTPS協(xié)議。如果鏈接無法訪問，商戶將無法接收到微信通知。 通知URL必須為直接可訪問的URL，不能攜帶參數(shù)。示例:
https://pay.wechatpay.cn
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見設(shè)置代金券消息通知地址接口文檔
# 3.2.15. 【服務(wù)端】核銷事件回調(diào)通知
步驟說明： 用戶使用券后，微信會把相關(guān)核銷券信息發(fā)送給商戶，商戶需要接收處理，并按照文檔規(guī)范返回應(yīng)答。出于安全的考慮，我們對核銷券信息數(shù)據(jù)進(jìn)行了加密，商戶需要先對通知數(shù)據(jù)進(jìn)行解密，才能得到核銷券信息數(shù)據(jù)。
注意
- 核銷券信息通知是以POST 方法訪問商戶設(shè)置的通知URL，通知的數(shù)據(jù)以JSON 格式通過請求主體（BODY）傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情
- 加密不能保證通知請求來自微信。微信會對發(fā)送給商戶的通知進(jìn)行簽名，并將簽名值放在通知的HTTP頭Wechatpay-Signature。商戶應(yīng)當(dāng)驗證簽名，以確認(rèn)請求來自微信，而不是其他的第三方。簽名驗證的算法請參考 《微信支付API v3簽名驗證》。
- 支付通知HTTP應(yīng)答碼為200或204才會當(dāng)作正常接收，當(dāng)回調(diào)處理異常時，應(yīng)答的HTTP狀態(tài)碼應(yīng)為500，或者4xx
- 商戶成功接收到回調(diào)通知后應(yīng)返回成功的HTTP應(yīng)答碼為200或204
- 同樣的通知可能會多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。 推薦的做法是，當(dāng)商戶系統(tǒng)收到通知進(jìn)行處理時，先檢查對應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài)，并判斷該通知是否已經(jīng)處理。如果未處理，則再進(jìn)行處理；如果已處理，則直接返回結(jié)果成功。在對業(yè)務(wù)數(shù)據(jù)進(jìn)行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進(jìn)行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂
- 對后臺通知交互時，如果微信收到應(yīng)答不是成功或超時，微信認(rèn)為通知失敗，微信會通過一定的策略定期重新發(fā)起通知，盡可能提高通知的成功率，但微信不保證通知最終能成功。（通知頻率為1min1次，總計9次）
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見核銷事件回調(diào)通知支付通知API接口文檔
# 4. 常見問題
# Q：創(chuàng)建代金券接口報錯：“你配置的信息需要開通特殊權(quán)限”
A：請按以下步驟進(jìn)行排查
stock_name：最多可填寫9個字
max_coupons_per_user：單天發(fā)放個數(shù)上限不能為0
coupon_amount：10<=coupon_amount<=100000
available_time_after_receive：可用時間：相對時間，按分鐘設(shè)置，是否1min<=分鐘范圍<=1440min
transaction_minimum校驗規(guī)則：
- 使用門檻-券面額>=0.01（門檻要大于面額）
- 0.1元<=門檻<=100000
stock_type：目前只支持NORMAL
out_request_no：校驗規(guī)則：不可以重復(fù)
開始時間結(jié)束時間控制在90天內(nèi)
不可使用的時間參數(shù)不可以傳遞
# Q：創(chuàng)建代金券報錯“批次預(yù)算等于批次面額乘以發(fā)券數(shù)”
A：請按以下步驟進(jìn)行排查
- max_amount需要等于coupon_amount（面額） * max_coupons（發(fā)放總上限）
- 核對最終請求數(shù)據(jù)，并查看是否存在遺漏數(shù)據(jù)，建議使用postman進(jìn)行調(diào)試
# Q：創(chuàng)建代金券報錯“活動未開始或已結(jié)束”
A：活動時間不能大于90天，請檢查available_begin_time、available_end_time參數(shù)設(shè)置是否符合要求。
# Q：激活代金券API，如果大于1min或者更久還報錯“系統(tǒng)繁忙”？
A：請檢查單個可用商戶號下正在運營的活動是否控制在500個以內(nèi)，若超過500個活動可能導(dǎo)致新活動激活失敗的情況。
# Q：設(shè)置消息通知地址報錯“系統(tǒng)繁忙”
A：請按以下步驟進(jìn)行排查
- 請檢查notify_url設(shè)置是否正確，notify_url必須為HTTPS
- notify_url地址為一個可訪問的地址
- notify_url不能攜帶參數(shù)。示例：
https://pay.wechatpay.cn/wxpay/pay.action
