# 1. 接口規(guī)則
為了在保證支付安全的前提下,帶給商戶簡單、一致且易用的開發(fā)體驗(yàn),我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請(qǐng)參考APIv3接口規(guī)則。
# 2. 開發(fā)準(zhǔn)備
# 2.1. 搭建和配置開發(fā)環(huán)境
為了幫助開發(fā)者調(diào)用開放接口,我們提供了JAVA、PHP、GO三種語言版本的開發(fā)庫,封裝了簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能(更多語言版本的開發(fā)庫將在近期陸續(xù)提供)。
測(cè)試步驟:
1、根據(jù)自身開發(fā)語言,選擇對(duì)應(yīng)的開發(fā)庫并構(gòu)建項(xiàng)目,具體配置請(qǐng)參考下面鏈接的詳細(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)建加載商戶私鑰、加載平臺(tái)證書、初始化httpClient的通用方法。
3、基于接口的示例代碼,替換請(qǐng)求參數(shù)后可發(fā)起測(cè)試。
說明:
- 上面的開發(fā)庫為微信支付官方開發(fā)庫,其它沒有審核或者控制下的第三方工具和庫,微信支付不保證它們的安全性和可靠性。通過包管理工具引入SDK后,可根據(jù)下面每個(gè)接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測(cè)試。
- 開發(fā)者如果想詳細(xì)了解簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實(shí)現(xiàn),可閱讀下面的詳細(xì)說明:
- 如想更詳細(xì)的了解我們的接口規(guī)則,可查看我們的接口規(guī)則指引文檔。
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
重點(diǎn)步驟說明:
步驟2 用戶確認(rèn)支付后,商戶調(diào)用微信支付Native下單API生成預(yù)支付交易以獲取支付二維碼鏈接code_url;
商戶調(diào)用Native下單API后,分正常返回和異常返回情況:
- 正常返回: 返回code_url,商戶可根據(jù)返回的code_url來生成調(diào)用OpenSDK的簽名以執(zhí)行下一步。
- 異常返回: 返回HTTP code或錯(cuò)誤碼,商戶可根據(jù)HTTP code列表 或錯(cuò)誤碼說明來排查原因并執(zhí)行下一步操作。
步驟4 商戶根據(jù)返回的code_url生成二維碼供用戶掃描,有關(guān)二維碼的規(guī)則請(qǐng)參考3.2.2部分的說明。
步驟9-11 商戶根據(jù)返回的code_url生成二維碼供用戶掃描,有關(guān)二維碼的規(guī)則請(qǐng)參考3.2.2部分的說明。
- 方法一: 支付結(jié)果通知。用戶支付成功后,微信支付會(huì)將支付成功的結(jié)果以回調(diào)通知的形式同步給商戶,商戶的回調(diào)地址需要在調(diào)用Native下單API時(shí)傳入notify_url參數(shù)。
- 方法二: 當(dāng)因網(wǎng)絡(luò)抖動(dòng)或本身notify_url存在問題等原因,導(dǎo)致無法接收到回調(diào)通知時(shí),商戶也可主動(dòng)調(diào)用查詢訂單API來獲取訂單狀態(tài)。
# 3.2. API接入(含示例代碼)
本章節(jié)展示了如何使用微信支付服務(wù)端 SDK 快速接入Native支付產(chǎn)品,完成與微信支付對(duì)接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法,代碼中的示例參數(shù)需替換成商戶自己賬號(hào)及請(qǐng)求參數(shù)才能跑通。
- 以下接入步驟僅提供參考,請(qǐng)商戶結(jié)合自身業(yè)務(wù)需求進(jìn)行評(píng)估、修改。
# 3.2.1. 【服務(wù)端】Native下單
步驟說明: 用戶在商戶PC網(wǎng)站內(nèi)完成商品選擇后進(jìn)入支付頁面,商戶需要通過后端請(qǐng)求該Native下單API來獲取支付二維碼鏈接code_url。
重要入?yún)⒄f明:
- out_trade_no: 商戶系統(tǒng)內(nèi)部訂單號(hào),只能是數(shù)字、大小寫字母_-*且在同一個(gè)商戶號(hào)下唯一。
- description: 商品描述。
- notify_url: 支付回調(diào)通知URL,該地址必須為直接可訪問的URL,不允許攜帶查詢串。
- total: 訂單總金額,單位為分。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見Native下單接口文檔。
# 3.2.2. 【客戶端】生成支付二維碼
步驟說明: 通過Native下單API成功獲取支付二維碼鏈接(code_url)后,需要在前端(PC網(wǎng)頁或POS機(jī)具)生成二維碼供用戶掃描支付。
注意
- code_url對(duì)應(yīng)鏈接格式:weixin://www.tg885.com/bizpayurl/up?pr=NwY5Mz9&groupid=00。請(qǐng)商戶調(diào)用第三方庫將code_url生成二維碼圖片。該模式鏈接較短,生成的二維碼打印到結(jié)賬小票上的識(shí)別率較高。
例如,weixin://www.tg885.com/bizpayurl/up?pr=NwY5Mz9&groupid=00 生成二維碼見下圖
- 更多二維碼的相關(guān)背景知識(shí)可參考
https://www.qrcode.com/zh/index.html (opens new window)
# 3.2.3. 【服務(wù)端】接收支付結(jié)果通知
步驟說明: 當(dāng)用戶完成支付,微信會(huì)把相關(guān)支付結(jié)果將通過異步回調(diào)的方式通知商戶,商戶需要接收處理,并按文檔規(guī)范返回應(yīng)答
注意
- 支付結(jié)果通知是以POST 方法訪問商戶設(shè)置的通知URL,通知的數(shù)據(jù)以JSON 格式通過請(qǐng)求主體(BODY)傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情。
- ature。商戶應(yīng)當(dāng)驗(yàn)證簽名,以確認(rèn)請(qǐng)求來自微信,而不是其他的第三方。簽名驗(yàn)證的算法請(qǐng)參考 《微信支付API v3簽名驗(yàn)證》。
- 支付通知HTTP應(yīng)答碼為200或204才會(huì)當(dāng)作正常接收,當(dāng)回調(diào)處理異常時(shí),應(yīng)答的HTTP狀態(tài)碼應(yīng)為500,或者4xx。
- 商戶成功接收到回調(diào)通知后應(yīng)返回成功的HTTP應(yīng)答碼為200或204。
- 同樣的通知可能會(huì)多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復(fù)的通知。 推薦的做法是,當(dāng)商戶系統(tǒng)收到通知進(jìn)行處理時(shí),先檢查對(duì)應(yīng)業(yè)務(wù)數(shù)據(jù)的狀態(tài),并判斷該通知是否已經(jīng)處理。如果未處理,則再進(jìn)行處理;如果已處理,則直接返回結(jié)果成功。在對(duì)業(yè)務(wù)數(shù)據(jù)進(jìn)行狀態(tài)檢查和處理之前,要采用數(shù)據(jù)鎖進(jìn)行并發(fā)控制,以避免函數(shù)重入造成的數(shù)據(jù)混亂。
- 對(duì)后臺(tái)通知交互時(shí),如果微信收到商戶的應(yīng)答不符合規(guī)范或超時(shí),微信認(rèn)為通知失敗,微信會(huì)通過一定的策略定期重新發(fā)起通知,盡可能提高通知的成功率,但微信不保證通知最終能成功。(通知頻率為15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 總計(jì) 24h4m)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見 支付結(jié)果通知接口文檔。
# 3.2.4. 【服務(wù)端】查詢訂單
步驟說明: 當(dāng)商戶后臺(tái)、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常,商戶系統(tǒng)最終未接收到支付通知時(shí),商戶可通過查詢訂單接口核實(shí)訂單支付狀態(tài)
注意
- 查詢訂單可通過微信支付訂單號(hào)和商戶訂單號(hào)兩種方式查詢,兩種查詢方式返回結(jié)果相同。
需要調(diào)用查詢接口的情況:
- 當(dāng)商戶后臺(tái)、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常,商戶系統(tǒng)最終未接收到支付通知。
- 調(diào)用支付接口后,返回系統(tǒng)錯(cuò)誤或未知交易狀態(tài)情況。
- 調(diào)用付款碼支付API,返回USERPAYING的狀態(tài)。
- 調(diào)用關(guān)單或撤銷接口API之前,需確認(rèn)支付狀態(tài)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見 微信支付訂單號(hào)/商戶訂單號(hào) 接口文檔。
# 3.2.5. 【服務(wù)端】關(guān)閉訂單
步驟說明: 當(dāng)商戶訂單支付失敗需要生成新單號(hào)重新發(fā)起支付,要對(duì)原訂單號(hào)調(diào)用關(guān)單,避免重復(fù)支付;系統(tǒng)下單后,用戶支付超時(shí),系統(tǒng)退出不再受理,避免用戶繼續(xù),請(qǐng)調(diào)用關(guān)單接口
注意
- 關(guān)單沒有時(shí)間限制,建議在訂單生成后間隔幾分鐘(最短5分鐘)再調(diào)用關(guān)單接口,避免出現(xiàn)訂單狀態(tài)同步不及時(shí)導(dǎo)致關(guān)單失敗。
- 已支付成功的訂單不能關(guān)閉。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見 關(guān)閉訂單通知API接口文檔。
# 3.2.6. 【服務(wù)端】申請(qǐng)交易賬單
步驟說明: 微信支付按天提供交易賬單文件,商戶可以通過該接口獲取賬單文件的下載地址。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見 申請(qǐng)交易賬單接口文檔。
# 3.2.7. 【服務(wù)端】下載賬單
步驟說明: 過申請(qǐng)交易賬單接口獲取到賬單下載地址(download_url)后,再通過該接口獲取到對(duì)應(yīng)的賬單文件,文件內(nèi)包含交易相關(guān)的金額、時(shí)間、營銷等信息,供商戶核對(duì)訂單、退款、銀行到賬等情況。
注意
- 賬單文件的下載地址的有效時(shí)間為30s。
- 強(qiáng)烈建議商戶將實(shí)際賬單文件的哈希值和之前從接口獲取到的哈希值進(jìn)行比對(duì),以確認(rèn)數(shù)據(jù)的完整性。
- 該接口響應(yīng)的信息請(qǐng)求頭中不包含微信接口響應(yīng)的簽名值,因此需要跳過驗(yàn)簽的流程。
- 微信在次日9點(diǎn)啟動(dòng)生成前一天的對(duì)賬單,建議商戶10點(diǎn)后再獲取。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見 下載賬單接口文檔。
# 4. 常見問題
# Q:微信native支付生成的二維碼有有效期嗎?
A:一個(gè)二維碼的有效期是根據(jù)Native下單接口返回的code_url決定,code_url的有效期是2小時(shí)。
# Q:native支付掃碼后提示:支付失敗,該商戶暫不支持通過長按識(shí)別二維碼完成支付
A:微信支付已經(jīng)不支持通過長按識(shí)別二維碼的方式或通過相冊(cè)識(shí)別二維碼的方式完成支付。