# 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ù)后進行快速測試。
- 開發(fā)者如果想詳細(xì)了解簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實現(xiàn),可閱讀下面的詳細(xì)說明:
- 如想更詳細(xì)的了解我們的接口規(guī)則,可查看我們的接口規(guī)則指引文檔。
# 2.2. 搭建和配置開發(fā)環(huán)境
- 微信支付分的相關(guān)配置參數(shù)在商戶入駐的過程中都已經(jīng)配置完成(前往查看配置相關(guān)內(nèi)容),例如授權(quán)結(jié)果回調(diào)URL、service_notify_url、測試白名單、免確認(rèn)訂單模式的權(quán)限等。
- 如果發(fā)現(xiàn)配置信息有誤,請主動聯(lián)系微信支付分運營同學(xué)協(xié)助修改,或者_點擊右側(cè)導(dǎo)航欄進入在線技術(shù)客服進行技術(shù)咨詢。
# 3. 快速接入(免確認(rèn)模式)
# 3.1. 業(yè)務(wù)流程圖
重點步驟說明:
步驟1 用戶在商戶側(cè)下單購買產(chǎn)品或服務(wù),此時,我們需要先對用戶的授權(quán)狀態(tài)進行查詢
查詢用戶授權(quán)狀態(tài)的兩種方法:
用戶授權(quán)狀態(tài)一共分三種:
UNAVAILABLE:用戶未授權(quán)服務(wù)
AVAILABLE:用戶已授權(quán)服務(wù)
UNBINDUSER:未綁定用戶
當(dāng)查詢到用戶授權(quán)狀態(tài)為UNAVAILABLE、UNBINDUSER時,請前往步驟二:引導(dǎo)用戶開啟服務(wù);
當(dāng)查詢到用戶授權(quán)狀態(tài)為AVAILABLE時,請前往步驟三:創(chuàng)建支付分訂單;
步驟2 引導(dǎo)用戶開啟授權(quán)服務(wù)
開啟授權(quán)有兩步操作,第一步:調(diào)用后臺接口進行預(yù)授權(quán),第二步:調(diào)用前端方法跳轉(zhuǎn)進入微信中讓用戶進行授權(quán)。
- (第一步)預(yù)授權(quán)后臺接口文檔詳見:商戶預(yù)授權(quán)API
- (第二步)跳轉(zhuǎn)進入微信授權(quán)根據(jù)用戶使用場景從以下三種方法選擇其一:App場景調(diào)起支付分-授權(quán)服務(wù)、JSAPI場景調(diào)起支付分-授權(quán)服務(wù)、小程序調(diào)起支付分-授權(quán)服務(wù)
請求開啟授權(quán)之后,我們需要確認(rèn)開啟授權(quán)是否成功,共有兩種方法:
1、通過接口主動查詢(未及時收到用戶授權(quán)成功通知情況下且用戶已回到商家授權(quán)頁面時商戶側(cè)主動查詢。)——查詢與用戶授權(quán)記錄(OpenID)、查詢與用戶授權(quán)記錄(授權(quán)協(xié)議號)
2、等待支付分的異步通知——開啟/解除授權(quán)結(jié)果回調(diào)通知
若獲取到用戶的授權(quán)狀態(tài)為AVAILABLE:用戶已授權(quán)服務(wù),則前往步驟三;
若獲取到用戶的授權(quán)狀態(tài)為UNAVAILABLE-用戶未授權(quán)服務(wù)、UNBINDUSER-未綁定用戶,則商戶可根據(jù)業(yè)務(wù)需要選擇繼續(xù)查詢或者結(jié)束支付分流程,進入商戶自己的業(yè)務(wù)流程。
步驟3 創(chuàng)建支付分訂單
我們通過創(chuàng)建支付分訂單API接口創(chuàng)建一筆待支付的支付分訂單。
請求:
入?yún)ⅰ皀eed_user_confirm”,取值請選擇 “false”;
入?yún)ⅰ皉isk_fund:name”,取值請選擇【先享模式】中的枚舉值。
返回:
- 若接口返回state=DOING:表示商戶創(chuàng)建服務(wù)訂單成功,可前往步驟四;
- 若接口返回state≠DOING:表示商戶創(chuàng)建服務(wù)訂單失敗,商戶可根據(jù)實際返回內(nèi)容提示選擇重新創(chuàng)建或者結(jié)束支付分流程,進入商戶自己的業(yè)務(wù)流程;
創(chuàng)建服務(wù)訂單失敗原因會在接口返回字段“message”中返回,主要失敗原因有兩種:
- 存在未完結(jié)訂單
- 綜合評估不通過,建議商戶稍后重試或者使用其他渠道支付
步驟4 商戶為用戶提供服務(wù),待服務(wù)結(jié)束后,商戶調(diào)用完結(jié)訂單接口完結(jié)當(dāng)前訂單。
調(diào)用完結(jié)支付分訂單API接口后,微信支付分就會發(fā)起對用戶的扣款,但是在用戶扣款過程中可能會出現(xiàn)一些特殊情況,下面列舉了幾種特殊情況以及對應(yīng)的處理方法,供大家參考:
請求:
- 情況一:扣款過程中,發(fā)現(xiàn)扣款金額有誤 (注意:此時需要訂單為“待支付”狀態(tài))
處理方法1:調(diào)用修改訂單金額接口修改訂單金額,系統(tǒng)將按照修改后的金額發(fā)起用戶扣款
處理方法2:調(diào)用取消支付分訂單接口取消待支付的支付分訂單
- 情況二:扣款過程中,用戶通過其它方式完成了支付,希望微信支付分停止繼續(xù)扣款
處理方法:商戶調(diào)用同步服務(wù)訂單信息接口將訂單支付成功狀態(tài)同步給微信支付分,微信支付分將停止繼續(xù)扣款的操作
步驟5 收到用戶扣款成功通知,業(yè)務(wù)流程結(jié)束
通過支付成功回調(diào)通知API接口可以獲取到用戶扣款成功的通知,同時,商戶也可以根據(jù)情況通過查詢支付分訂單API接口主動查詢扣款情況。
- 如訂單狀態(tài)state=DONE,且收款狀態(tài)collection.state=USER_PAID,代表扣款成功
- 如訂單狀態(tài)state=DOING,state_description=MCH_COMPLETE,且收款狀態(tài)collection.state=USER_PAYING,代表扣款進行中
如遇到網(wǎng)絡(luò)、服務(wù)器等原因造成無法正常接收扣款成功通知,一般有兩種解決方法:
- 主動查單,通過查詢支付分訂單API 接口主動查詢扣款情況
- 次日對賬,通過申請交易賬單API接口申請交易賬單,再通過后臺接口下載賬單API下載交易賬單
# 3.2. API接入(含示例代碼)
本文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入微信支付分產(chǎn)品,完成與微信支付對接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法,代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。
- 以下接入步驟僅提供參考,請商戶結(jié)合自身業(yè)務(wù)需求進行評估、修改。
# 3.2.1. 【服務(wù)端】查詢用戶授權(quán)關(guān)系
步驟說明: 創(chuàng)建支付分訂單的前提是用戶必須有授權(quán)關(guān)系,所以在免確認(rèn)模式下,我們最先要做的就是確保用戶是已授權(quán)狀態(tài)。目前提供了使用OpenID和授權(quán)協(xié)議號兩種條件進行查詢的方式。下面以查詢用戶授權(quán)記錄(OpenID)舉例接口調(diào)用方式。
重要入?yún)⒄f明:
- 查詢條件參數(shù)OpenID或者授權(quán)協(xié)議號都是在接口URL中傳遞的,請勿傳到body中去。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢用戶授權(quán)記錄(OpenID)接口文檔。
# 3.2.2. 【服務(wù)端】請求預(yù)授權(quán)接口
步驟說明: 創(chuàng)建支付分訂單的前提是用戶必須有授權(quán)關(guān)系,所以在免確認(rèn)模式下,我們最先要做的就是確保用戶是已授權(quán)狀態(tài)。通過商戶預(yù)授權(quán)接口獲取跳轉(zhuǎn)用戶授權(quán)頁必填參數(shù)“預(yù)授權(quán)token”。
重要入?yún)⒄f明:
- 完成用戶授權(quán)需要兩步操作,預(yù)授權(quán)接口僅是為獲取關(guān)鍵參數(shù)“預(yù)授權(quán)token”,商戶還需引導(dǎo)用戶跳轉(zhuǎn)到微信授權(quán)頁進行授權(quán)操作。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 商戶預(yù)授權(quán)API接口文檔。
# 3.2.3. 【客戶端】開啟授權(quán)服務(wù)
步驟說明: 通過商戶預(yù)授權(quán)接口獲取到跳轉(zhuǎn)用戶授權(quán)頁必填參數(shù)“預(yù)授權(quán)token”后,即可通過前端方法跳轉(zhuǎn)到微信客戶端,讓用戶開啟授權(quán)服務(wù)。前端跳轉(zhuǎn)方法請根據(jù)用戶實際使用場景(App、小程序、微信內(nèi)H5)來選擇。
# 3.2.4. 【服務(wù)端】開啟/解除授權(quán)服務(wù)回調(diào)通知
步驟說明: 當(dāng)用戶授權(quán)或解約服務(wù)成功時,微信會把相關(guān)信息異步回調(diào)的方式通知商戶,商戶需要接收處理,并按文檔規(guī)范返回應(yīng)答
注意
- 支付結(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ù)混亂。
- 如果在所有通知頻率(4小時)后沒有收到微信側(cè)回調(diào),商戶應(yīng)調(diào)用查詢訂單接口確認(rèn)訂單狀態(tài)。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見開啟/解除授權(quán)服務(wù)回調(diào)通知API接口文檔。
# 3.2.5. 【服務(wù)端】創(chuàng)建支付分訂單
步驟說明: 完成用戶授權(quán)后,即可創(chuàng)建支付分訂單,為用戶提供服務(wù)了。
重要參數(shù)說明:
- 入?yún)ⅰ皀eed_user_confirm”,取值請選擇 “false”;
- 入?yún)ⅰ皉isk_fund:name”,取值請選擇【先享模式】中的枚舉值。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 創(chuàng)建支付分訂單API接口文檔。
# 3.2.6. 【服務(wù)端】完結(jié)支付分訂單
步驟說明: 用戶服務(wù)結(jié)束后,商戶通過請求完結(jié)支付分訂單接口,通過微信支付分進行用戶扣款操作。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 完結(jié)支付分訂單API接口文檔。
# 3.2.7. 【服務(wù)端】修改訂單金額
步驟說明: 在用戶扣款成功前、完結(jié)訂單后(即訂單狀態(tài)為“待支付”),如需修改訂單支付金額,可通過此接口進行訂單金額修改。修改成功后,微信支付將按照修改后的金額進行用戶扣款。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見修改訂單金額API接口文檔。
# 3.2.8. 【服務(wù)端】取消支付分訂單
步驟說明: 訂單為以下狀態(tài)時可以取消訂單:CREATED(已創(chuàng)單)、DOING(進行中)(包括商戶完結(jié)支付分訂單后,且支付分訂單收款狀態(tài)為待支付USER_PAYING)。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見取消支付分訂單API接口文檔。
# 3.2.9. 【服務(wù)端】同步服務(wù)訂單信息
步驟說明: 由于一些原因,用戶與商戶達成線下支付或者其他支付方式支付的協(xié)議,商戶可通過此接口告知微信支付該筆訂單無需繼續(xù)扣款,微信支付在接到此信息后將不再發(fā)起用戶扣款。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 同步服務(wù)訂單信息API接口文檔。
# 3.2.10. 【服務(wù)端】查詢支付分訂單
步驟說明: 一般在創(chuàng)建訂單后、訂單完結(jié)成功后等關(guān)鍵流程中,商戶可能有知曉訂單狀態(tài)的需求,此時即可通過該接口查詢訂單狀態(tài)。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 查詢支付分訂單API接口文檔。
# 3.2.11. 【服務(wù)端】申請交易賬單
步驟說明: 微信支付按天提供交易賬單文件,商戶可以通過該接口獲取賬單文件的下載地址。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 申請交易賬單API接口文檔。
# 3.2.12. 【服務(wù)端】下載交易賬單
步驟說明: 通過申請交易賬單接口獲取到賬單下載地址(download_url)后,再通過該接口獲取到對應(yīng)的賬單文件,文件內(nèi)包含交易相關(guān)的金額、時間、營銷等信息,供商戶核對訂單、退款、銀行到賬等情況
注意
- 賬單文件的下載地址的有效時間為30s
- 強烈建議商戶將實際賬單文件的哈希值和之前從接口獲取到的哈希值進行比對,以確認(rèn)數(shù)據(jù)的完整性
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 下載賬單API接口文檔。
# 3.2.13. 【服務(wù)端】支付成功回調(diào)通知
步驟說明: 當(dāng)用戶完成支付,微信會把相關(guān)支付結(jié)果將通過異步回調(diào)的方式通知商戶,商戶需要接收處理,并按文檔規(guī)范返回應(yīng)答
注意
- 支付結(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ù)混亂。
- 如果在所有通知頻率(4小時)后沒有收到微信側(cè)回調(diào),商戶應(yīng)調(diào)用查詢訂單接口確認(rèn)訂單狀態(tài)。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 支付成功回調(diào)通知API接口文檔。
# 3.2.14. 【服務(wù)端】解除用戶授權(quán)關(guān)系
步驟說明: 如果用戶或者商戶有解除授權(quán)關(guān)系的需求,可通過該接口進行“解約”。我們提供了兩種解約方式:使用簽約協(xié)議號和使用用戶OpenID進行解約,下面我們以使用用戶OpenID解約為例,進行代碼演示。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 解除用戶授權(quán)關(guān)系A(chǔ)PI接口文檔。
# 3.2.15. 【客戶端】跳轉(zhuǎn)訂單詳情
微信支付根據(jù)用戶不同的使用場景(App、小程序、微信內(nèi)H5)分別提供了對應(yīng)跳轉(zhuǎn)訂單詳情頁的方法,請根據(jù)場景進行選擇,詳見跳轉(zhuǎn)訂單詳情頁API文檔
# 4. 常見問題
# Q:商戶小程序跳轉(zhuǎn)支付分小程序(詳情頁,授權(quán)頁)報錯“未通過申請,當(dāng)前服務(wù)未上線”
A:檢查測試微信是否開通白名單,提供服務(wù)ID和微信號聯(lián)系運營開通白名單
# Q:創(chuàng)建支付分訂單返回{"code":"NO_AUTH","message":"商戶暫無權(quán)限使用此服務(wù)"}
A:
- 檢查商戶號和AppID是否配置了通用化接口權(quán)限,可以聯(lián)系微信側(cè)運營確認(rèn)和配置通用化接口權(quán)限
- 如果商戶開通的是免確認(rèn)訂單權(quán)限,創(chuàng)建訂單時need_user_confirm只能傳false,如果商戶開通的是含確認(rèn)訂單權(quán)限,創(chuàng)建訂單時need_user_confirm只能傳true
# Q:創(chuàng)建支付分訂單返回{"code":"PARAM_ERROR","message":"訂單風(fēng)險金額名稱不符合要求"}
A:檢查商戶號開通的是哪種模式的權(quán)限,需確認(rèn)模式可以使用先免模式與先享模式,免確認(rèn)模式只能使用先享模式
# Q:免確認(rèn)訂單模式創(chuàng)建支付分訂單報錯{"code":"INVALID_REQUEST","message":"綜合評估不通過"}是什么原因
A:表示免確認(rèn)流程創(chuàng)單用戶被不對外風(fēng)控攔截
# Q:調(diào)用支付分創(chuàng)單接口報錯返回“mch_id和AppID未綁定”如何處理?
A:請商戶自行檢查mch_id和AppID是否有對應(yīng)的綁定關(guān)系。綁定步驟參考:商家商戶號與AppID賬號關(guān)聯(lián)管理 (opens new window)