# 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ā)配置
# 2.2.1. 開通H5支付權(quán)限
- 前往微信支付服務(wù)商平臺 (opens new window)—>產(chǎn)品中心—>特約商戶授權(quán)產(chǎn)品—>服務(wù)商H5支付->申請開通。
# 2.2.2.服務(wù)器配置要求
- 登錄【微信支付服務(wù)商平臺 (opens new window)—>產(chǎn)品中心—>開發(fā)配置—>H5支付】，設(shè)置后一般10分鐘內(nèi)生效。
注意
- 域名必須通過ICP備案
- 域名填寫格式不包含
http://或https://
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
# 安全標(biāo)準(zhǔn)規(guī)范流程圖
重點步驟說明：
步驟1 用戶向商戶系統(tǒng)后臺請求下單，商戶后臺必須做好安全校驗。
- 當(dāng)跨域請求不是簡單請求 (opens new window)時，瀏覽器會發(fā)起Options預(yù)檢請求 (opens new window)，此時商戶后臺需要支持Options請求且校驗Origin頭部，如果不在允許的白名單列表內(nèi)，則返回403且不返回
Access-Control-Allow-*相關(guān)頭部。 - 針對GET/POST的跨域下單請求，商戶后臺需要校驗Origin頭部是否合法且用戶Cookie是否完備（若用戶未登陸則先引導(dǎo)登陸商戶站點），否則返回403且不返回
Access-Control-Allow-*相關(guān)頭部。
步驟2 商戶可通過H5下單API創(chuàng)建支付訂單。
步驟3 用戶通過微信外部的瀏覽器調(diào)起微信支付中間頁，進行發(fā)起支付請求。
步驟5 用戶支付成功后，商戶可接收到微信支付支付結(jié)果通知支付通知API。
步驟8 商戶在沒有接收到微信支付結(jié)果通知的情況下需要主動調(diào)用商戶訂單號查詢訂單查詢支付結(jié)果。
注意
- 商戶需按照安全規(guī)范進行接入，若因未遵循規(guī)范接入而出現(xiàn)安全問題，財付通將根據(jù)《微信支付服務(wù)協(xié)議》 (opens new window)條款處理
- 以上圖示，僅為示例，只供參考。請商戶自行確認是否實現(xiàn)了跨域訪問白名單限制和用戶登錄態(tài)校驗。
# 3.2. API接入（含示例代碼）
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入支付有禮，完成與微信支付對接的部分。
注意
- 文檔中的代碼示例是用來闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請商戶結(jié)合自身業(yè)務(wù)需求進行評估、修改。
# 3.2.1. 【服務(wù)端】H5下單
步驟說明： 用戶使用微信外部的瀏覽器訪問商戶H5頁面，當(dāng)用戶選擇相關(guān)商品購買時，商戶系統(tǒng)先調(diào)用該接口在微信支付服務(wù)后臺生成預(yù)支付交易單。
重要入?yún)⒄f明：
- out_trade_no： 商戶系統(tǒng)內(nèi)部訂單號，只能是數(shù)字、大小寫字母_-*且在同一個商戶號下唯一。
- description： 商品描述。
- notify_url： 支付回調(diào)通知URL，該地址必須為直接可訪問的URL，不允許攜帶查詢串。
- total： 訂單總金額，單位為分。
- scene_info： 支付場景描述。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見H5下單接口文檔。
# 3.2.2. 【客戶端】微信外部的瀏覽器拉起微信支付中間頁
步驟說明： 通過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.3.【服務(wù)端】接收支付結(jié)果通知
步驟說明： 當(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)驗證簽名，以確認請求來自微信，而不是其他的第三方。簽名驗證的算法請參考 《微信支付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ù)混亂。
- 對后臺通知交互時，如果微信收到商戶的應(yīng)答不符合規(guī)范或超時，微信認為通知失敗，微信會通過一定的策略定期重新發(fā)起通知，盡可能提高通知的成功率，但微信不保證通知最終能成功。（通知頻率為15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 總計 24h4m）。
特別提醒： 商戶系統(tǒng)對于開啟結(jié)果通知的內(nèi)容一定要做簽名驗證，并校驗通知的信息是否與商戶側(cè)的信息一致，防止數(shù)據(jù)泄露導(dǎo)致出現(xiàn)“假通知”，造成資金損失。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 支付結(jié)果通知接口文檔。
# 3.2.4. 【服務(wù)端】查詢訂單
步驟說明： 當(dāng)商戶后臺、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常，商戶系統(tǒng)最終未接收到支付通知時，商戶可通過查詢訂單接口核實訂單支付狀態(tài)。
注意
需要調(diào)用查詢接口的情況：
- 當(dāng)商戶后臺、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常，商戶系統(tǒng)最終未接收到支付通知。
- 調(diào)用支付接口后，返回系統(tǒng)錯誤或未知交易狀態(tài)情況。
- 調(diào)用付款碼支付API，返回USERPAYING的狀態(tài)。
- 調(diào)用關(guān)單或撤銷接口API之前，需確認支付狀態(tài)。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 微信支付訂單號/商戶訂單號接口文檔
# 3.2.5. 【服務(wù)端】關(guān)閉訂單
步驟說明： 當(dāng)商戶訂單支付失敗需要生成新單號重新發(fā)起支付，要對原訂單號調(diào)用關(guān)單，避免重復(fù)支付；系統(tǒng)下單后，用戶支付超時，系統(tǒng)退出不再受理，避免用戶繼續(xù)，請調(diào)用關(guān)單接口
注意
- 關(guān)單沒有時間限制，建議在訂單生成后間隔幾分鐘（最短5分鐘）再調(diào)用關(guān)單接口，避免出現(xiàn)訂單狀態(tài)同步不及時導(dǎo)致關(guān)單失敗。
- 已支付成功的訂單不能關(guān)閉。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 關(guān)閉訂單接口文檔。
# 3.2.6. 【服務(wù)端】申請交易賬單
步驟說明： 微信支付按天提供交易賬單文件，商戶可以通過該接口獲取賬單文件的下載地址。
示例代碼：
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 申請交易賬單接口文檔
# 3.2.7. 【服務(wù)端】下載賬單
步驟說明： 通過申請交易賬單接口獲取到賬單下載地址（download_url）后，再通過該接口獲取到對應(yīng)的賬單文件，文件內(nèi)包含交易相關(guān)的金額、時間、營銷等信息，供商戶核對訂單、退款、銀行到賬等情況
注意
- 賬單文件的下載地址的有效時間為30s。
- 強烈建議商戶將實際賬單文件的哈希值和之前從接口獲取到的哈希值進行比對，以確認數(shù)據(jù)的完整性。
- 該接口響應(yīng)的信息請求頭中不包含微信接口響應(yīng)的簽名值，因此需要跳過驗簽的流程。
- 微信在次日9點啟動生成前一天的對賬單，建議商戶10點后再獲取。
更多參數(shù)、響應(yīng)詳情及錯誤碼請參見 下載賬單接口文檔
# 4. 常見問題
# Q：調(diào)起H5支付報"商家參數(shù)格式有誤，請聯(lián)系商家解決"
A：請按以下幾點進行排查：
- 當(dāng)前調(diào)起H5支付的referer為空導(dǎo)致，一般是因為直接訪問頁面調(diào)起H5支付，請按正常流程進行頁面跳轉(zhuǎn)后發(fā)起支付，或自行抓包確認referer值是否為空。
- 如果是App里調(diào)起H5支付，需要在webview中手動設(shè)置referer，如(Map extraHeaders = new HashMap();extraHeaders.put("Referer", "商戶申請H5時提交的授權(quán)域名");//例如
https://pay.wechatpay.cn)。
# Q：調(diào)起H5支付報"商家存在未配置的參數(shù)，請聯(lián)系商家解決"
A：請按以下幾點進行排查：
- 當(dāng)前調(diào)起H5支付的域名（微信側(cè)從referer中獲取）與申請H5支付時提交的授權(quán)域名不一致，如需添加或修改授權(quán)域名，請登錄商戶號對應(yīng)的【商戶平臺 -> 產(chǎn)品中心 -> 開發(fā)配置】自行配置。
- 如果設(shè)置了回跳地址redirect_url，請確認設(shè)置的回跳地址的域名與申請H5支付時提交的授權(quán)域名是否一致。
# Q：調(diào)起H5支付報"支付請求已失效，請重新發(fā)起支付"
A：H5下單返回的H5_URL生成后，有效期為5分鐘，如超時請重新生成H5_URL后再發(fā)起支付。
# Q：調(diào)用App下單接口，返回“sub_appid與sub_mch_id不匹配”
A：H5支付不能直接在微信客戶端內(nèi)調(diào)起，請在外部瀏覽器調(diào)起。
# Q：調(diào)起H5支付報" 簽名驗證失敗"或“系統(tǒng)繁忙，請稍后再試”
A：請按以下幾點進行排查：
- 請確認同一個H5_URL只被一個微信號調(diào)起，如果不同微信號調(diào)起請重新下單生成新的H5_URL。
- 如H5_URL有添加redirect_url，請確認參數(shù)拼接格式是否有誤，是否有對redirect_url的值做urlencode,可參考以下例子格式：
https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096&redirect_url=https%3A%2F%2Fwww.wechatpay.com.cn。
# Q：IOS在使用某些瀏覽器完成H5支付后會回到safari瀏覽器
A：完成H5支付后需通過scheme信息返回調(diào)起支付的瀏覽器，但由于部分瀏覽器隱藏了這個信息，在無法拿到scheme信息的情況下，就會默認回到safari瀏覽器。
