# 1. 接口規(guī)則
為了在保證支付安全的前提下,帶給商戶簡單、一致且易用的開發(fā)體驗,我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請參考APIv3接口規(guī)則。
# 2. 開發(fā)準備
# 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ā)者。
- 注:當前開發(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ī)則指引文檔。
# 2.2. 業(yè)務(wù)開發(fā)配置
合單支付目前支持在微信外H5、App、JSAPI、小程序、Native掃碼5個場景使用,下面為你介紹JSAPI場景業(yè)務(wù)開發(fā)配置。
# 2.2.1. 設(shè)置支付目錄
一、支付授權(quán)目錄說明:
商戶最后請求拉起微信支付收銀臺的頁面地址我們稱之為“支付目錄”,例如:
https://www.weixin.com/pay.php
。商戶實際的支付目錄必須和在微信支付商戶平臺設(shè)置的一致,否則會報錯“當前頁面的URL未注冊:”
二、支付授權(quán)目錄設(shè)置說明:
登錄【微信支付服務(wù)商平臺 (opens new window) > 產(chǎn)品中心 > 開發(fā)配置】,設(shè)置后一般5分鐘內(nèi)生效。(配置頁見下圖)
三、支付授權(quán)目錄校驗規(guī)則說明:
如果支付授權(quán)目錄設(shè)置為頂級域名(例如:
https://www.weixin.com/
),那么只校驗頂級域名,不校驗后綴;如果支付授權(quán)目錄設(shè)置為多級目錄,就會進行全匹配,例如設(shè)置支付授權(quán)目錄為
https://www.weixin.com/abc/123
/,則實際請求頁面目錄不能為https://www.weixin.com/abc/
,也不能為https://www.weixin.com/abc/123/pay/
,必須為https://www.weixin.com/abc/123/
。
# 2.2.2. 設(shè)置授權(quán)域名
授權(quán)域名說明:開發(fā)JSAPI支付時,在JSAPI下單接口中要求必傳用戶OpenID,而獲取OpenID則需要您在公眾平臺設(shè)置獲取OpenID的域名,只有被設(shè)置過的域名才是一個有效的獲取OpenID的域名,否則將獲取失敗。具體配置頁見下圖。
授權(quán)域名設(shè)置說明:登錄【微信公眾平臺 (opens new window) > 公眾號設(shè)置】。
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
業(yè)務(wù)流程時序圖如下。
重點步驟說明:
步驟1:用戶在商戶側(cè)發(fā)起支付請求,商戶先通過后臺接口合單下單-JSAPI接口創(chuàng)建合單支付訂單。
步驟2:商戶再根據(jù)用戶發(fā)起支付請求的具體場景通過合單下單-JSAPI頁面調(diào)起微信支付收銀臺,完成支付請求。
步驟3:用戶支付成功后,商戶可接收到支付結(jié)果回調(diào)通知。
步驟4:如果商戶長時間未收到回調(diào)通知,可通過合單查詢訂單接口主動查詢訂單支付狀態(tài)。
# 3.2. API接入(含示例代碼)
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入商家券產(chǎn)品,完成與微信支付對接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法,代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。
- 以下接入步驟僅提供參考,請商戶結(jié)合自身業(yè)務(wù)需求進行評估、修改。
# 3.2.1. 【服務(wù)端】合單下單-JSAPI
步驟說明:用戶在商戶側(cè)選擇商品下單購買時,商戶系統(tǒng)先調(diào)用該接口在微信支付服務(wù)后臺生成預(yù)支付交易單,然后使用我們提供的客戶端方法(下文介紹)調(diào)起微信支付收銀臺,即可完成支付。
示例代碼:
重要入?yún)⒄f明:
- out_trade_no:商戶系統(tǒng)內(nèi)部訂單號,可以是數(shù)字、大小寫字母_-*的任意組合,且在同一個商戶號下唯一。
- description:商品描述。
- notify_url:支付回調(diào)通知URL,該地址必須為直接可訪問的URL,不允許攜帶查詢串。
- total:訂單總金額,單位為分。
- OpenID:OpenID是微信用戶在AppID下的唯一用戶標識(AppID不同,則獲取到的OpenID就不同),可用于永久標記一個用戶。OpenID獲取方式請參考以下文檔小程序獲取OpenID (opens new window)、公眾號獲取OpenID (opens new window)、App獲取OpenID (opens new window)。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見合單下單-JSAPI。
# 3.2.2.【客戶端】JSAPI調(diào)起支付
步驟說明:通過合單下單API成功獲取預(yù)支付交易會話標識(prepay_id)后,需要通過JSAPI調(diào)起支付API來調(diào)起微信支付收銀臺。
注意
- WeixinJSBridge內(nèi)置對象在其他瀏覽器中無效。
- 此API需要將請求參數(shù)進行簽名(參與簽名的參數(shù)為:
appId
、timeStamp
、nonceStr
、package
,參數(shù)區(qū)分大小寫)。
示例代碼:
1function onBridgeReady() {2 WeixinJSBridge.invoke('getBrandWCPayRequest', {3 "appId": "wx2421b1c4370ecxxx", //公眾號ID,由商戶傳入4 "timeStamp": "1395712654", //時間戳,自1970年以來的秒數(shù)5 "nonceStr": "e61463f8efa94090b1f366cccfbbb444", //隨機串6 "package": "prepay_id=up_wx21201855730335ac86f8c43d1889123400",7 "signType": "RSA", //微信簽名方式:8 "paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\/X+QBhcCYL21N7cHCTUxbQ+EAt6Uy+lwSN22f5YZvI45MLko8Pfso0jm46v5hqcVwrk6uddkGuT+Cdvu4WBqDzaDjnNa5UK3GfE1Wfl2gHxIIY5lLdUgWFts17D4WuolLLkiFZV+JSHMvH7eaLdT9N5GBovBwu5yYKUR7skR8Fu+LozcSqQixnlEZUfyE55feLOQTUYzLmR9pNtPbPsu6WVhbNHMS3Ss2+AehHvz+n64GDmXxbX++IOBvm2olHu3PsOUGRwhudhVf7UcGcunXt8cqNjKNqZLhLw4jq\/xDg==" //微信簽名9 },10 function(res) {11 if (res.err_msg == "get_brand_wcpay_request:ok") {12 // 使用以上方式判斷前端返回,微信團隊鄭重提示:13 //res.err_msg將在用戶支付成功后返回ok,但并不保證它絕對可靠。14 }15 });16}17if (typeof WeixinJSBridge == "undefined") {18 if (document.addEventListener) {19 document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);20 } else if (document.attachEvent) {21 document.attachEvent('WeixinJSBridgeReady', onBridgeReady);22 document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);23 }24} else {25 onBridgeReady();26}
重要入?yún)⒄f明:
- package:JSAPI下單接口返回的prepay_id參數(shù)值,提交格式如:
prepay_id=***
。 - signType:該接口V3版本僅支持RSA
- paySign:簽名
paySign生成規(guī)則、響應(yīng)詳情及錯誤碼請參見JSAPI調(diào)起支付接口文檔。
# 3.2.3.【服務(wù)端】接收支付結(jié)果通知
步驟說明:當用戶完成支付,微信會把相關(guān)支付結(jié)果將通過異步回調(diào)的方式通知商戶,商戶需要接收處理,并按文檔規(guī)范返回應(yīng)答。
- 支付結(jié)果通知的地址需要在請求App下單API時傳入
notify_url
參數(shù)中。 - 支付結(jié)果通知是以POST 方法訪問商戶設(shè)置的通知URL,通知的數(shù)據(jù)以JSON 格式通過請求主體(BODY)傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情。
- 加密不能保證通知請求來自微信。微信會對發(fā)送給商戶的通知進行簽名,并將簽名值放在通知的HTTP頭
Wechatpay-Signature
。商戶應(yīng)當驗證簽名,以確認請求來自微信,而不是其他的第三方。簽名驗證的算法請參考 《微信支付API v3簽名驗證》。 - 支付結(jié)果通知HTTP應(yīng)答碼為200或204才會當作正常接收,當回調(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ù)的通知。
- 后臺通知交互時,如果微信收到商戶的應(yīng)答不符合規(guī)范或超時,微信會判定本次通知失敗,重新發(fā)送通知,直到成功為止,但微信不保證通知最終一定能成功。
特別提醒:
- 商戶系統(tǒng)對于支付結(jié)果通知的內(nèi)容一定要做簽名驗證,并校驗返回的訂單金額是否與商戶側(cè)的訂單金額一致,防止數(shù)據(jù)泄露導(dǎo)致出現(xiàn)“假通知”,造成資金損失。
- 當收到通知進行處理時,首先檢查對應(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)詳情及錯誤碼請參見支付結(jié)果通知API接口文檔。
# 3.2.4. 【服務(wù)端】合單查詢訂單
步驟說明:當商戶后臺、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常,商戶系統(tǒng)最終未接收到支付結(jié)果通知時商戶可通過查詢訂單接口核實訂單支付狀態(tài)。
示例代碼:
注意
- 查詢訂單可通過合單商戶訂單號查詢。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢訂單API接口文檔。
# 3.2.5. 【服務(wù)端】合單關(guān)閉訂單
步驟說明:當商戶訂單支付失敗需要生成新單號重新發(fā)起支付,要對原訂單號調(diào)用關(guān)單,避免重復(fù)支付;系統(tǒng)下單后,用戶支付超時,系統(tǒng)退出不再受理,避免用戶繼續(xù),請調(diào)用關(guān)單接口。
示例代碼:
注意
- 訂單生成后不能馬上調(diào)用關(guān)單接口,最短調(diào)用時間間隔為5分鐘。
- 已支付成功的訂單不能關(guān)閉。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見合單關(guān)單API接口文檔。
# 3.2.6. 【服務(wù)端】申請交易賬單
步驟說明:微信支付按天提供交易賬單文件,商戶可以通過該接口獲取賬單文件的下載地址。
示例代碼:
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見申請交易賬單接口文檔。
# 3.2.7. 【服務(wù)端】下載賬單
步驟說明:通過申請交易賬單接口獲取到賬單下載地址(download_url)后,再通過該接口獲取到對應(yīng)的賬單文件,文件內(nèi)包含交易相關(guān)的金額、時間、營銷等信息,供商戶核對訂單、退款、銀行到賬等情況。
示例代碼:
注意
- 賬單文件的下載地址的有效時間為30s。
- 強烈建議商戶將實際賬單文件的哈希值和之前從接口獲取到的哈希值進行比對,以確認數(shù)據(jù)的完整性。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見下載賬單接口文檔。
# 4. 常見問題
問: 獲取OpenID接口報“此公眾號并沒有這些scope的權(quán)限,錯誤碼10005”,如下圖所示。
答: 請按以下步驟進行排查:
- 建議檢查一下公眾號的功能。比如是不是在訂閱號/未認證的公眾號里面嘗試調(diào)用認證服務(wù)號的功能。
- 確認AppID是否認證過期或者AppID填寫錯誤。
- 請嘗試使用snsapi_userinfo的授權(quán)登錄方式。
問: JSAPI調(diào)起支付接口報“商家暫時沒有此類交易權(quán)限,請聯(lián)系商家客服”。
答:請按以下步驟進行排查:
- 請檢查你的下單接口是否指定了支付用戶的身份,該功能需單獨開通指定身份支付權(quán)限方可使用
- 請確認你使用的商戶號是否有jsapi支付的權(quán)限,可登錄商戶平臺-產(chǎn)品中心查看
問:JSAPI調(diào)起支付接口報“當前頁面的URL未注冊”。
答:請檢查下單接口中使用的商戶號是否在服務(wù)商平臺 (opens new window)配置了對應(yīng)的支付目錄,可參考“2.2.3.1.設(shè)置支付目錄”章節(jié)說明。
問:獲取OpenID接口報“redirect_url域名與后臺配置不一致,錯誤碼:10003”。
答:請按以下步驟進行排查:
- 本錯誤是公眾號獲取OpenID接口報的錯誤,可參考文檔檢查是否符合開發(fā)規(guī)范:網(wǎng)頁授權(quán) (opens new window)
- 檢查下單接口傳的AppID與獲取OpenID接口的AppID是否同一個(需一致)。
- 檢查AppID對應(yīng)的公眾號后臺 (opens new window),是否配置的授權(quán)域名和獲取OpenID的域名一致。授權(quán)域名配置路徑:【公眾平臺 (opens new window)-> 設(shè)置-> 公眾號設(shè)置-> 功能設(shè)置–> 網(wǎng)頁授權(quán)域名】。
問:JSAPI調(diào)起支付接口報“該商戶暫不支持通過外部拉起微信完成支付”。
答:JSAPI支付只能從微信瀏覽器內(nèi)發(fā)起支付請求。