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