# 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ā)配置
普通支付目前支持在微信外H5、App、JSAPI、小程序、Native掃碼5個場景使用,下面依次為你介紹這5個場景需求進行的業(yè)務(wù)開發(fā)配置:
# 2.2.1. 微信外H5場景開發(fā)配置
步驟說明: 平臺可通過此接口添加分賬接收方,建立分賬接收方列表。后續(xù)通過發(fā)起分賬請求,將平臺下的二級商戶結(jié)算后的資金,分給分賬接收方列表中具體的分賬接收方。
開通H5支付權(quán)限:前往【微信支付商戶平臺 (opens new window)—>產(chǎn)品中心—>H5支付—>申請開通】。
設(shè)置H5支付域名:登錄【微信支付商戶平臺 (opens new window)—>產(chǎn)品中心—>開發(fā)配置—>H5支付】,設(shè)置后一般10分鐘內(nèi)生效。
注意
- 域名必須通過ICP備案
- 域名填寫格式不包含"HTTP://"或"HTTPS://"
# 2.2.2. App場景開發(fā)配置
# 一、注冊App
App接入微信支付,需要先將商戶App在微信開放平臺進行注冊,登記App開發(fā)參數(shù)以生成AppID。具體操作步驟如下:
登錄微信開放平臺 (opens new window),進入【管理中心 → 移動應(yīng)用 → 創(chuàng)建移動應(yīng)用】;
完成基本信息的錄入,商戶需要在本步驟提交App對應(yīng)的下載地址,應(yīng)用官網(wǎng),應(yīng)用水印,icon等業(yè)務(wù)信息;
完成平臺信息的錄入,商戶需要在本步驟提交App在Android及iOS端對應(yīng)的開發(fā)參數(shù),包括Android端應(yīng)用的包名,應(yīng)用簽名,iOS端應(yīng)用的bundle ID,universal link等;
注意
- Android應(yīng)用包名和簽名的相關(guān)說明,請參考Android開發(fā)要點說明。
以上信息全部提交完成后,即完成App的注冊,商戶可在【管理中心 → 移動應(yīng)用】中,選擇具體的應(yīng)用查看其AppID及已獲得的接口能力;
獲取到App的AppID后,需要將該AppID與商戶的收款mch_id進行綁定,商戶可登錄商戶平臺后前往【產(chǎn)品中心 -> AppID賬號管理】界面中進行AppID的綁定及管理,界面如圖所示。
# 二、iOS開發(fā)要點說明
- iOS系統(tǒng)OpenSDK升級指引:
由于蘋果公司在iOS13系統(tǒng)回收了查詢 App bundleID 的能力,導(dǎo)致微信無法保證授權(quán)憑證能正確返回給AppID對應(yīng)的應(yīng)用。為此,微信支付強烈要求所有商戶盡快升級到OpenSDK1.8.6,并讓用戶及時更新App,否則安全風(fēng)險將一直存在。謝謝配合!
詳細OpenSDK升級指引請參見:OpenSDK升級指引 (opens new window)
注意
OpenSDK升級后請一定按照文檔要求完成驗證工作,確保OpenSDK升級成功。
- 開發(fā)配置:
以下項目開發(fā)環(huán)境以Xcode6.0,運行環(huán)境為IOS7.0為例,說明其開發(fā)中需要的操作。
項目設(shè)置AppID
商戶在微信開放平臺申請開發(fā)App應(yīng)用后,微信開放平臺會生成App的唯一標(biāo)識AppID。在Xcode中打開項目,設(shè)置項目屬性中的URL,Schemes為您的AppID。如下圖標(biāo)紅位置所示。
注冊AppID
商戶App工程中引入微信lib庫和頭文件,調(diào)用API前,需要先向微信注冊您的AppID,代碼如下:
[WXApi registerApp:@"wxd930ea5d5a258f4f" withDescription:@"demo 2.0"];
注意
- OpenSDK前端拉起支付及SDK回調(diào)的相關(guān)說明,請參考App調(diào)起支付。
# 三、Android開發(fā)要點說明
后臺設(shè)置
商戶在微信開放平臺申請開發(fā)應(yīng)用后,微信開放平臺會生成App的唯一標(biāo)識AppID。由于需要保證支付安全,需要在開放平臺綁定商戶應(yīng)用包名和應(yīng)用簽名,設(shè)置好后才能正常發(fā)起支付。設(shè)置界面在【開放平臺】 (opens new window)中的欄目【管理中心-> 修改應(yīng)用 -> 修改開發(fā)信息】里面,如下圖紅框內(nèi)所示。
應(yīng)用包名:是在App項目配置文件AndroidManifest.xml中聲明的package值,例如圖中的package="demo.wxpay.tenpay.com"。
應(yīng)用簽名:根據(jù)項目的應(yīng)用包名和編譯使用的keystore,可由簽名工具生成一個32位的md5串,在調(diào)試的手機上安裝簽名工具后,運行可生成應(yīng)用簽名串,如下圖所示,綠色串即應(yīng)用簽名。簽名工具下載地址 (opens new window)。
注冊AppID
商戶App工程中引入微信JAR包,調(diào)用API前,需要先向微信注冊您的AppID,代碼如下:
final IWXAPI msgApi = WXAPIFactory.createWXAPI(context, null);
// 將該App注冊到微信
msgApi.registerApp("wxd930ea5d5a258f4f");
# 2.2.3. JSAPI場景開發(fā)配置
# 設(shè)置支付目錄
支付授權(quán)目錄說明:
- 商戶最后請求拉起微信支付收銀臺的頁面地址我們稱之為“支付目錄”,例如:
https://www.weixin.com/pay.php
。 - 商戶實際的支付目錄必須和在微信支付商戶平臺設(shè)置的一致,否則會報錯“當(dāng)前頁面的URL未注冊”。
- 商戶最后請求拉起微信支付收銀臺的頁面地址我們稱之為“支付目錄”,例如:
支付授權(quán)目錄設(shè)置說明:
- 登錄【微信支付服務(wù)商平臺 (opens new window)-->產(chǎn)品中心-->開發(fā)配置】,設(shè)置后一般5分鐘內(nèi)生效(不支持設(shè)置端口號)。
支付授權(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/
- 如果支付授權(quán)目錄設(shè)置為頂級域名(例如:
# 設(shè)置授權(quán)域名
授權(quán)域名說明: 開發(fā)JSAPI支付時,在JSAPI下單接口中要求必傳用戶OpenID,而獲取OpenID則需要您在公眾平臺設(shè)置獲取OpenID的域名,只有被設(shè)置過的域名才是一個有效的獲取OpenID的域名,否則將獲取失敗。
授權(quán)域名設(shè)置說明: 登錄微信公眾平臺 (opens new window)-->公眾號設(shè)置
# 2.2.4. 小程序場景開發(fā)配置
賬號申請指引:
小程序開通微信支付,即申請或復(fù)用微信支付商戶號 申請完小程序后,登錄小程序后臺 (opens new window)。點擊左側(cè)導(dǎo)航欄的微信支付,在頁面中進行開通。(開通申請要求小程序已發(fā)布上線)
點擊開通按鈕后,有2種方式可以獲取微信支付能力,新申請微信支付商戶號或綁定一個已有的微信支付商戶號,請根據(jù)你的業(yè)務(wù)需要和具體情況選擇,只能二選一。詳見微信支付商戶接入指引 (opens new window)
服務(wù)器配置要求:
- 小程序訪問商戶服務(wù)都是通過HTTPS,開發(fā)部署的時候需要HTTPS服務(wù)器。
- 服務(wù)器域名配置。
- 每個微信小程序需要事先設(shè)置通訊域名,小程序只可以跟指定的域名進行網(wǎng)絡(luò)通信。包括普通 HTTPS 請求(wx.request)、上傳文件(wx.uploadFile)、下載文件(wx.downloadFile)和 WebSocket 通信(wx.connectSocket)。
- 從基礎(chǔ)庫 2.4.0 開始,網(wǎng)絡(luò)接口允許與局域網(wǎng) IP 通信,但要注意 不允許與本機 IP 通信。
注意
- 域名只支持 HTTPS (wx.request、wx.uploadFile、wx.downloadFile) 和 wss (wx.connectSocket) 協(xié)議。
- 域名不能使用 IP 地址(小程序的局域網(wǎng) IP 除外)或 localhost。
- 可以配置端口,如
https://myserver.com:8080
,但是配置后只能向https://myserver.com:8080/
發(fā)起請求。如果向https://myserver.com
、https://myserver.com:9091
等 URL請求則會失敗。 - 如果不配置端口。如
https://myserver.com
,那么請求的 URL 中也不能包含端口,甚至是默認(rèn)的 443 端口也不可以。如果向https://myserver.com:443
請求則會失敗。 - 域名必須經(jīng)過 ICP 備案。
- 出于安全考慮,
api.weixin.qq.com
不能被配置為服務(wù)器域名,相關(guān)API也不能在小程序內(nèi)調(diào)用。 開發(fā)者應(yīng)將 AppSecret 保存到后臺服務(wù)器中,通過服務(wù)器使用 getAccessToken 接口獲取 access_token,并調(diào)用相關(guān) API。 - 不支持配置父域名,使用子域名。
- 可查閱小程序網(wǎng)絡(luò)請求 (opens new window)以了解更多信息。
# 2.2.5. Native掃碼場景開發(fā)配置
暫無需特殊配置內(nèi)容
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
重要步驟說明:
步驟1 用戶在商戶側(cè)發(fā)起支付請求,商戶先通過后臺接口基礎(chǔ)下單接口創(chuàng)建預(yù)支付訂單。
步驟2 商戶再根據(jù)用戶發(fā)起支付請求的具體場景通過微信外H5/App/公眾號頁面調(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ù)端】基礎(chǔ)下單
步驟說明: 用戶在商戶側(cè)選擇商品下單購買時,商戶系統(tǒng)先調(diào)用該接口在微信支付服務(wù)后臺生成預(yù)支付交易單,然后使用我們提供的客戶端方法(下文介紹)調(diào)起微信支付收銀臺,即可完成支付。
目前平臺收付通基礎(chǔ)下單接口支持3個場景:微信外H5、App、JSAPI,請注意這3個場景對應(yīng)的基礎(chǔ)下單接口地址都不同,請勿混淆使用:
https://api.mch.weixin.qq.com/v3/pay/partner/transactions/h5
——微信外H5場景普通下單接口地址。
https://api.mch.weixin.qq.com/v3/pay/partner/transactions/app
——App場景普通下單接口地址。
https://api.mch.weixin.qq.com/v3/pay/partner/transactions/jsapi
——JSAPI/小程序場景普通下單接口地址。
https://api.mch.weixin.qq.com/v3/pay/partner/transactions/native
——Native場景普通下單接口地址。
下面以JSAPI場景為例,為你展示JSAPI下單接口的請求示例:
重要入?yún)⒄f明:
- out_trade_no: 商戶系統(tǒng)內(nèi)部訂單號,只能是數(shù)字、大小寫字母_-*且在同一個商戶號下唯一。
- description: 商品描述。
- notify_url: 支付回調(diào)通知URL,該地址必須為直接可訪問的URL,不允許攜帶查詢串。
- total: 訂單總金額,單位為分。
- OpenID: OpenID是微信用戶在AppID下的唯一用戶標(biāo)識(AppID不同,則獲取到的OpenIDd就不同),可用于永久標(biāo)記一個用戶。OpenID獲取方式請參考以下文檔:小程序獲取OpenID (opens new window) 、公眾號獲取OpenID (opens new window) 、App獲取OpenID (opens new window)。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 JSAPI下單、App下單、小程序下單接口、H5下單接口、Native下單接口文檔。
# 3.2.2.【客戶端】JSAPI調(diào)起支付
步驟說明: 通過JSAPI下單API成功獲取預(yù)支付交易會話標(biāo)識(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.【客戶端】App調(diào)起支付
步驟說明: 通過App下單API成功獲取預(yù)支付交易會話標(biāo)識(prepay_id)后,需要通過OpenSDK來調(diào)起微信支付收銀臺。
注意
- 該步驟請使用開放平臺的官方OpenSDK,可前往開放平臺資源中心 (opens new window)下載。
- SDK的調(diào)用需要攜帶簽名(參與簽名的參數(shù)為:AppID、partnerid、prepayid、package、noncestr、timestamp,參數(shù)區(qū)分大小寫)。
重要入?yún)⒄f明:
- package: 取固定值Sign=WXPay。
- signType: 該接口V3版本僅支持RSA。
- paySign: 簽名。
paySign生成規(guī)則、響應(yīng)詳情及錯誤碼請參見App調(diào)起支付接口文檔。
# iOS SDK調(diào)用說明
一、拉起支付
商戶服務(wù)器生成支付訂單,先調(diào)用App下單API生成預(yù)付單,獲取到prepay_id后將參數(shù)再次簽名傳輸給App發(fā)起支付。以下是調(diào)起微信支付的關(guān)鍵代碼:
1PayReq *request = [[[PayReq alloc] init] autorelease];2request.partnerId = @"10000100";3request.prepayId= @"1101000000140415649af9fc314aa427";4request.package = @"Sign=WXPay";5request.nonceStr= @"a462b76e7436e98e0ed6e13c64b4fd1c";6request.timeStamp= @"1397527777";7request.sign= @"582282D72DD2B03AD892830965F428CB16E7A256";8[WXApi sendReq:request]
該sign生成字段名列表見App調(diào)起支付接口文檔。
二、SDK結(jié)果回調(diào)
照微信SDK Sample,在類實現(xiàn)onResp函數(shù),支付完成后,微信App會返回到商戶App并回調(diào)onResp函數(shù),開發(fā)者需要在該函數(shù)中接收通知,判斷返回錯誤碼,如果支付成功則去后臺查詢支付結(jié)果再展示用戶實際支付結(jié)果。注意 一定不能以客戶端返回作為用戶支付的結(jié)果,應(yīng)以服務(wù)器端的接收的支付通知或查詢API返回的結(jié)果為準(zhǔn)。 代碼示例如下:
1-(void)onResp:(BaseResp*)resp{2 if ([respisKindOfClass:[PayRespclass]]){3 PayResp*response=(PayResp*)resp;4 switch(response.errCode){5 caseWXSuccess: //服務(wù)器端查詢支付通知或查詢API返回的結(jié)果再提示成功6 NSlog(@"支付成功");7 break;8 default:9 NSlog(@"支付失敗,retcode=%d",resp.errCode);10 break;11 }12 }13}
回調(diào)中errCode值列表:
名稱 | 描述 | 解決方案 |
---|---|---|
-2 | 用戶取消 | 無需處理。發(fā)生場景:用戶不支付了,點擊取消,返回App。 |
-1 | 錯誤 | 可能的原因:簽名錯誤、未注冊AppID、項目設(shè)置AppID不正確、注冊的AppID與設(shè)置的不匹配、其他異常等。 |
0 | 成功 | 展示成功頁面 |
# Android SDK調(diào)用說明
一、SDK拉起支付
商戶服務(wù)器生成支付訂單,先調(diào)用【App下單API】生成預(yù)付單,獲取到prepay_id后將參數(shù)再次簽名傳輸給App發(fā)起支付。以下是調(diào)起微信支付的關(guān)鍵代碼:
1IWXAPI api;2PayReq request = new PayReq();3request.appId = "wxd930ea5d5a258f4f";4request.partnerId = "1900000109";5request.prepayId= "1101000000140415649af9fc314aa427",;6request.packageValue = "Sign=WXPay";7request.nonceStr= "1101000000140429eb40476f8896f4c9";8request.timeStamp= "1398746574";9request.sign= "7FFECB600D7157C5AA49810D2D8F28BC2811827B";10api.sendReq(request);
該sign生成字段名列表見調(diào)起支付API
二、支付結(jié)果回調(diào)
參照微信SDK Sample,在商戶包名.wxapi包路徑中實現(xiàn)WXPayEntryActivity類(包名或類名不一致會造成無法回調(diào)),在WXPayEntryActivity類中實現(xiàn)onResp函數(shù),支付完成后,微信App會返回到商戶App并回調(diào)onResp函數(shù),開發(fā)者需要在該函數(shù)中接收通知,判斷返回錯誤碼,如果支付成功則去后臺查詢支付結(jié)果再展示用戶實際支付結(jié)果。注意一定不能以客戶端返回作為用戶支付的結(jié)果,應(yīng)以服務(wù)器端的接收的支付通知或查詢API返回的結(jié)果為準(zhǔn)。 代碼示例如下:
1public void onResp(BaseRespresp){2 if(resp.getType()==ConstantsAPI.COMMAND_PAY_BY_WX){3 Log.d(TAG,"onPayFinish,errCode="+resp.errCode);4 AlertDialog.Builderbuilder=newAlertDialog.Builder(this);5 builder.setTitle(R.string.app_tip);6 }7}
回調(diào)中errCode值列表:
名稱 | 描述 | 解決方案 |
---|---|---|
0 | 成功 | 展示成功頁面 |
-1 | 錯誤 | 可能的原因:簽名錯誤、未注冊AppID、項目設(shè)置AppID不正確、注冊的AppID與設(shè)置的不匹配、其他異常等。 |
-2 | 用戶取消 | 無需處理。發(fā)生場景:用戶不支付了,點擊取消,返回App。 |
# 3.2.4. 【客戶端】微信外H5瀏覽器拉起微信支付中間頁
**步驟說明:**通過H5下單API接口成功獲取H5下單返回的支付中間頁(h5_url)后,用戶需要通過微信外部的瀏覽器調(diào)起微信支付收銀臺
注意
- h5_url為拉起微信支付收銀臺的中間頁面,可通過訪問該URL來拉起微信客戶端,完成支付,h5_url的有效期為5分鐘。
- 微信支付收銀臺中間頁會進行H5權(quán)限的校驗,安全性檢查。
- 正常流程用戶支付完成后會返回至發(fā)起支付的頁面,如需返回至指定頁面,則可以在h5_url后拼接上redirect_url參數(shù),來指定回調(diào)頁面。您希望用戶支付完成后跳轉(zhuǎn)至
https://www.wechatpay.com.cn
,則拼接后的地址為h5_url=https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096&redirect_url=https%3A%2F%2Fwww.wechatpay.com.cn
。 - 需對redirect_url進行urlencode處理。
- 由于設(shè)置redirect_url后,回跳指定頁面的操作可能發(fā)生在:
- 微信支付中間頁調(diào)起微信收銀臺后超過5秒。
- 用戶點擊“取消支付”或支付完成后點“完成”按鈕。因此無法保證頁面回跳時,支付流程已結(jié)束,所以商戶設(shè)置的redirect_url地址不能自動執(zhí)行查單操作,應(yīng)讓用戶去點擊按鈕觸發(fā)查單操作,回跳頁面展示效果可參考下圖。
# 3.2.5. 【客戶端】生成支付二維碼
步驟說明: 通過Native下單API成功獲取支付二維碼鏈接(code_url)后,需要在前端(PC網(wǎng)頁或POS機具)生成二維碼供用戶掃描支付。
注意
code_url對應(yīng)鏈接格式:weixin://weixin://pay.wechatpay.cn/bizpayurl/up?pr=NwY5Mz9&groupid=00。請商戶調(diào)用第三方庫將code_url生成二維碼圖片。該模式鏈接較短,生成的二維碼打印到結(jié)賬小票上的識別率較高。
例如,將
weixin://weixin://pay.wechatpay.cn/bizpayurl/up?pr=NwY5Mz9&groupid=00
生成二維碼建下圖更多二維碼的相關(guān)背景知識可參考
# 3.2.6.【服務(wù)端】接收支付結(jié)果通知
步驟說明: 當(dāng)用戶完成支付,微信會把相關(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)當(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ù)的通知。
- 后臺通知交互時,如果微信收到商戶的應(yīng)答不符合規(guī)范或超時,微信會判定本次通知失敗,重新發(fā)送通知,直到成功為止,但微信不保證通知最終一定能成功。
特別提醒:
- 商戶系統(tǒng)對于支付結(jié)果通知的內(nèi)容一定要做簽名驗證,并校驗返回的訂單金額是否與商戶側(cè)的訂單金額一致,防止數(shù)據(jù)泄露導(dǎo)致出現(xiàn)“假通知”,造成資金損失。
- 當(dā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.7. 【服務(wù)端】查詢訂單
步驟說明: 當(dāng)商戶后臺、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常,商戶系統(tǒng)最終未接收到支付通知時商戶可通過查詢訂單接口核實訂單支付狀態(tài)。
注意
- 查詢訂單可通過微信支付訂單號或商戶訂單號兩種方式查詢,兩種查詢方式返回結(jié)果相同
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 查詢訂單API接口文檔
# 3.2.8. 【服務(wù)端】關(guān)閉訂單
步驟說明: 當(dāng)商戶訂單支付失敗需要生成新單號重新發(fā)起支付,要對原訂單號調(diào)用關(guān)閉訂單,避免重復(fù)支付;系統(tǒng)下單后,用戶支付超時,系統(tǒng)退出不再受理,避免用戶繼續(xù),請調(diào)用關(guān)閉訂單接口
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 關(guān)閉訂單API接口文檔
# 3.2.9.【服務(wù)端】申請交易賬單
**步驟說明:**微信支付按天提供交易賬單文件,商戶可以通過該接口獲取賬單文件的下載地址
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見申請交易賬單API 接口文檔
# 3.2.10.【服務(wù)端】下載賬單
步驟說明: 通過申請交易賬單接口獲取到賬單下載地址(download_url)后,再通過該接口獲取到對應(yīng)的賬單文件,文件內(nèi)包含交易相關(guān)的金額、時間、營銷等信息,供商戶核對訂單、退款、銀行到賬等情況
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 下載賬單API (opens new window)接口文檔