# 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)建項目,具體配置請參考下面鏈接的詳細說明:
- 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ù)后進行快速測試。
- 開發(fā)者如果想詳細了解簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實現(xiàn),可閱讀下面的詳細說明:
- 如想更詳細的了解我們的接口規(guī)則,可查看我們的接口規(guī)則指引文檔。
# 2.2. 業(yè)務(wù)開發(fā)配置-分賬
需分賬的訂單,平臺在下單時需預(yù)先打上分賬標(biāo)識“profit_sharing”,詳細可查看各場景下單API(普通支付下單/合單支付下單API)。
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖-分賬
重要步驟說明:
步驟1 平臺通過添加分賬接收方API添加需要分賬的分賬對象(接收方)。
步驟2 平臺預(yù)先在合單支付/普通支付下單API接口中上傳分賬標(biāo)識“profit_sharing”,待訂單完成支付后即可調(diào)用請求分賬API接口發(fā)起分賬請求。
步驟3 分賬完成后,微信會通過分賬動賬通知API接口,主動通知商戶。商戶如有需要,可以通過查詢分賬結(jié)果API接口,主動查詢分賬結(jié)果。
步驟4 分賬后若產(chǎn)生退款,則需先調(diào)用請求分賬回退API 接口,請求將已經(jīng)分給分賬方的資金回退,再處理退款。
步驟5 分賬回退完成后,微信同樣會通過分賬動賬通知API接口,主動通知商戶。商戶也可以通過查詢分賬回退結(jié)果API接口,主動查詢分賬結(jié)果。
步驟6: 分賬結(jié)束后,商戶需調(diào)用完結(jié)分賬API接口結(jié)束分賬訂單。
# 3.2. API接入-分賬
本文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入平臺收付通產(chǎn)品,完成與微信支付對接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法,代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。
- 以下接入步驟僅提供參考,請商戶結(jié)合自身業(yè)務(wù)需求進行評估、修改。
# 3.2.1.【服務(wù)端】添加分賬接收方
步驟說明: 平臺可通過此接口添加分賬接收方,建立分賬接收方列表。后續(xù)通過發(fā)起分賬請求,將平臺下的二級商戶結(jié)算后的資金,分給分賬接收方列表中具體的分賬接收方。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見添加分賬接收方API接口文檔。
# 3.2.2.【服務(wù)端】請求分賬
步驟說明: 平臺,如有訂單需要進行分賬,可通過此接口完成。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見請求分賬API接口文檔。
# 3.2.3.【服務(wù)端】分賬動賬通知
步驟說明: 此功能僅針對分賬接收方,當(dāng)分賬動賬金額發(fā)生變動時,微信會把相關(guān)變動結(jié)果發(fā)送給需要實時關(guān)注的分賬接收方。
注意
- 支付結(jié)果通知是以POST 方法訪問商戶設(shè)置的通知URL,通知的數(shù)據(jù)以JSON 格式通過請求主體(BODY)傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情。
- 加密不能保證通知請求來自微信。微信會對發(fā)送給商戶的通知進行簽名,并將簽名值放在通知的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)收到通知進行處理時,先檢查對應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài),并判斷該通知是否已經(jīng)處理。如果未處理,則再進行處理;如果已處理,則直接返回結(jié)果成功。在對業(yè)務(wù)數(shù)據(jù)進行狀態(tài)檢查和處理之前,要采用數(shù)據(jù)鎖進行并發(fā)控制,以避免函數(shù)重入造成的數(shù)據(jù)混亂。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見分賬動賬通知API接口文檔。
# 3.2.4. 【服務(wù)端】查詢分賬結(jié)果
步驟說明: 平臺可通過此接口實時關(guān)注訂單的分賬請求和分賬完結(jié)情況。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 查詢分賬結(jié)果API接口文檔。
# 3.2.5. 【服務(wù)端】請求分賬回退
步驟說明: 訂單已經(jīng)分賬,在退款時,可以先調(diào)此接口,將已分賬的資金從分賬接收方的賬戶回退給分賬方,再發(fā)起退款。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見請求分賬回退API 接口文檔。
# 3.2.6. 【服務(wù)端】查詢分賬回退結(jié)果
步驟說明: 商戶需要核實回退結(jié)果,可調(diào)用此接口查詢回退結(jié)果;如果分賬回退接口返回狀態(tài)為處理中,可調(diào)用此接口查詢回退結(jié)果。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢分賬回退結(jié)果API 接口文檔。
# 3.2.7. 【服務(wù)端】完結(jié)分賬
步驟說明: 不需要進行分賬的訂單,可直接調(diào)用本接口將訂單的金額全部解凍給二級商戶。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見完結(jié)分賬API接口文檔。
# 3.2.8. 【服務(wù)端】查詢訂單剩余待分金額
步驟說明: 分賬接口支持對一筆訂單進行多次分賬,在這過程中,你可以使用該接口查詢訂單剩余的可進行分賬的金額。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢訂單剩余待分金額API接口文檔。
# 3.2.9. 【服務(wù)端】刪除分賬接收方
步驟說明: 平臺發(fā)起刪除分賬接收方請求。刪除后,不支持將平臺下二級商戶結(jié)算后的資金,分到該分賬接收方。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 刪除分賬接收方API接口文檔。