# 1. 接口規(guī)則
為了在保證支付安全的前提下，帶給商戶簡(jiǎn)單、一致且易用的開(kāi)發(fā)體驗(yàn)，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請(qǐng)參考APIv3接口規(guī)則。
# 2. 開(kāi)發(fā)準(zhǔn)備
# 2.1. 搭建和配置開(kāi)發(fā)環(huán)境
為了幫助開(kāi)發(fā)者調(diào)用開(kāi)放接口，我們提供了JAVA、PHP、GO三種語(yǔ)言版本的開(kāi)發(fā)庫(kù)，封裝了簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語(yǔ)言版本的開(kāi)發(fā)庫(kù)將在近期陸續(xù)提供）。
測(cè)試步驟：
1、根據(jù)自身開(kāi)發(fā)語(yǔ)言，選擇對(duì)應(yīng)的開(kāi)發(fā)庫(kù)并構(gòu)建項(xiàng)目，具體配置請(qǐng)參考下面鏈接的詳細(xì)說(shuō)明：
- wechatpay-java (opens new window)（推薦）、wechatpay-apache-httpclient (opens new window)，適用于Java開(kāi)發(fā)者。
- 注：當(dāng)前開(kāi)發(fā)指引接口JAVA示例代碼采用wechatpay-apache-httpclient版本。
- wechatpay-php (opens new window)（推薦）、wechatpay-guzzle-middleware (opens new window)，適用于PHP開(kāi)發(fā)者。
- 注：當(dāng)前開(kāi)發(fā)指引接口PHP示例代碼采用wechatpay-guzzle-middleware版本。
- wechatpay-go (opens new window)，適用于Go開(kāi)發(fā)者。
更多資源可前往微信支付開(kāi)發(fā)者社區(qū) (opens new window)搜索查看。
2、創(chuàng)建加載商戶私鑰、加載平臺(tái)證書(shū)、初始化httpClient的通用方法。
3、基于接口的示例代碼，替換請(qǐng)求參數(shù)后可發(fā)起測(cè)試。
說(shuō)明：
- 上面的開(kāi)發(fā)庫(kù)為微信支付官方開(kāi)發(fā)庫(kù)，其它沒(méi)有審核或者控制下的第三方工具和庫(kù)，微信支付不保證它們的安全性和可靠性。通過(guò)包管理工具引入SDK后，可根據(jù)下面每個(gè)接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測(cè)試。
- 開(kāi)發(fā)者如果想詳細(xì)了解簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實(shí)現(xiàn)，可閱讀下面的詳細(xì)說(shuō)明：
- 簽名生成
- 簽名驗(yàn)證
- 敏感信息加解密
- merchantPrivateKey（私鑰）
- wechatpayCertificates（平臺(tái)證書(shū)）
- APIV3Key（V3 key）
- 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。
# 2.2. 業(yè)務(wù)開(kāi)發(fā)配置
# 2.2.1. 設(shè)置支付目錄
1. 支付授權(quán)目錄說(shuō)明：
1. 支付授權(quán)目錄說(shuō)明：
1）服務(wù)商最后請(qǐng)求拉起微信支付收銀臺(tái)的頁(yè)面地址我們稱之為“支付授權(quán)目錄”，例如：https://www.weixin.com/pay.php (opens new window)的支付授權(quán)目錄為：https://www.weixin.com/ (opens new window)。
2）服務(wù)商實(shí)際的支付授權(quán)目錄必須和在微信支付服務(wù)商平臺(tái)設(shè)置的一致，否則會(huì)報(bào)錯(cuò)“當(dāng)前頁(yè)面的URL未注冊(cè)：”
3）服務(wù)商模式支付授權(quán)目錄設(shè)置可分為2種方式：
- 服務(wù)商為全體子商戶設(shè)置支付授權(quán)目錄
- 服務(wù)商為某一子商戶單獨(dú)設(shè)置支付授權(quán)目錄
2. 支付授權(quán)目錄設(shè)置說(shuō)明：
1）服務(wù)商為全體子商戶設(shè)置支付授權(quán)目錄
登錄微信支付【服務(wù)商平臺(tái) (opens new window)->產(chǎn)品中心->開(kāi)發(fā)配置】，設(shè)置后一般5分鐘內(nèi)生效。
2）服務(wù)商為某一子商戶單獨(dú)設(shè)置支付授權(quán)目錄
登錄微信支付【服務(wù)商平臺(tái) (opens new window)->服務(wù)商功能—>特約商戶管理】，設(shè)置后一般5分鐘內(nèi)生效。
3. 支付授權(quán)目錄校驗(yàn)規(guī)則說(shuō)明：
- 如果支付授權(quán)目錄設(shè)置為頂級(jí)域名（例如：
https://www.weixin.com/），那么只校驗(yàn)頂級(jí)域名，不校驗(yàn)后綴； - 如果支付授權(quán)目錄設(shè)置為多級(jí)目錄，就會(huì)進(jìn)行全匹配，例如設(shè)置支付授權(quán)目錄為
https://www.weixin.com/abc/123/，則實(shí)際請(qǐng)求頁(yè)面目錄不能為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)域名說(shuō)明：開(kāi)發(fā)JSAPI支付時(shí)，在JSAPI下單接口中要求必傳用戶OpenID，而獲取OpenID則需要您在公眾平臺(tái)設(shè)置獲取OpenID的域名，只有被設(shè)置過(guò)的域名才是一個(gè)有效的獲取OpenID的域名，否則將獲取失敗。具體配置頁(yè)如圖2所示:
- 授權(quán)域名設(shè)置說(shuō)明：登錄【微信公眾平臺(tái) (opens new window)->公眾號(hào)設(shè)置->功能設(shè)置】
# 3. 快速接入
# 3.1. 業(yè)務(wù)流程圖
重點(diǎn)步驟說(shuō)明：
步驟3 用戶下單發(fā)起支付，商戶可通過(guò)JSAPI下單創(chuàng)建支付訂單。
步驟8 商戶可在微信瀏覽器內(nèi)通過(guò)JSAPI調(diào)起支付API調(diào)起微信支付，發(fā)起支付請(qǐng)求。
步驟15 用戶支付成功后，商戶可接收到微信支付支付結(jié)果通知支付結(jié)果通知API。
步驟20 商戶在沒(méi)有接收到微信支付結(jié)果通知的情況下需要主動(dòng)調(diào)用查詢訂單API查詢支付結(jié)果。
# 3.2. API接入（含示例代碼）
文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入支付有禮，完成與微信支付對(duì)接的部分。
注意
- 文檔中的代碼示例是用來(lái)闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號(hào)及請(qǐng)求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請(qǐng)商戶結(jié)合自身業(yè)務(wù)需求進(jìn)行評(píng)估、修改。
# 3.2.1. 【服務(wù)端】JSAPI下單
步驟說(shuō)明：
用戶通過(guò)商戶下發(fā)的模板消息或掃描二維碼在微信內(nèi)進(jìn)入商戶網(wǎng)頁(yè)，當(dāng)用戶選擇相關(guān)商戶購(gòu)買(mǎi)時(shí)，商戶系統(tǒng)先調(diào)用該接口在微信支付服務(wù)后臺(tái)生成預(yù)支付交易單。
重要入?yún)⒄f(shuō)明：
- out_trade_no： 商戶系統(tǒng)內(nèi)部訂單號(hào)，只能是數(shù)字、大小寫(xiě)字母_-*且在同一個(gè)商戶號(hào)下唯一。
- description： 商品描述。
- notify_url： 支付回調(diào)通知URL，該地址必須為直接可訪問(wèn)的URL，不允許攜帶查詢串。
- total： 訂單總金額，單位為分。
- OpenID： OpenID是微信用戶在AppID下的唯一用戶標(biāo)識(shí)（AppID不同，則獲取到的OpenID就不同），可用于永久標(biāo)記一個(gè)用戶。OpenID獲取方式請(qǐng)參考以下文檔小程序獲取OpenID (opens new window)、公眾號(hào)獲取OpenID (opens new window)、App獲取OpenID (opens new window)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)JSAPI下單接口文檔。
# 3.2.2. 【客戶端】JSAPI調(diào)起支付
步驟說(shuō)明： 通過(guò)JSAPI下單API成功獲取預(yù)支付交易會(huì)話標(biāo)識(shí)（prepay_id）后，需要通過(guò)JSAPI調(diào)起支付API來(lái)調(diào)起微信支付收銀臺(tái)。
注意
- WeixinJSBridge內(nèi)置對(duì)象在其他瀏覽器中無(wú)效。
- 此API需要將請(qǐng)求參數(shù)進(jìn)行簽名（參與簽名的參數(shù)為：AppID、timeStamp、nonceStr、package，參數(shù)區(qū)分大小寫(xiě)）。
- 請(qǐng)確保實(shí)際支付時(shí)的請(qǐng)求目錄與后臺(tái)配置的目錄一致（現(xiàn)在已經(jīng)支持配置根目錄，配置后有一定的生效時(shí)間，一般5分鐘內(nèi)生效），否則將無(wú)法成功喚起微信支付。配置方式詳見(jiàn)支付授權(quán)目錄。
- WeixinJSBridge內(nèi)置對(duì)象在其他瀏覽器中無(wú)效。
- JSSDK的wx.chooseWXPay喚起支付，喚起格式內(nèi)容參考公眾號(hào)開(kāi)發(fā)指南 (opens new window)。
- JSSDK的JSSDK使用步驟說(shuō)明鏈接地址，內(nèi)容說(shuō)明信息 (opens new window)。
- 喚起支付返回的res對(duì)象駝峰式是JSSDK返回的格式，而err_msg是WeixinJSBridge返回的格式，如商戶使用不同的方式，此處響應(yīng)的字符大小寫(xiě)、格式需注意。
重要入?yún)⒄f(shuō)明：
- package： JSAPI下單接口返回的prepay_id參數(shù)值，提交格式如：prepay_id=***。
- signType： 該接口V3版本僅支持RSA。
- paySign： 簽名。
paySign生成規(guī)則、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) JSAPI調(diào)起支付接口文檔。
# 3.2.3. 【服務(wù)端】接收支付結(jié)果通知
步驟說(shuō)明： 當(dāng)用戶完成支付，微信會(huì)把相關(guān)支付結(jié)果將通過(guò)異步回調(diào)的方式通知商戶，商戶需要接收處理，并按文檔規(guī)范返回應(yīng)答
注意
- 支付結(jié)果通知是以POST 方法訪問(wèn)商戶設(shè)置的通知URL，通知的數(shù)據(jù)以JSON 格式通過(guò)請(qǐng)求主體（BODY）傳輸。通知的數(shù)據(jù)包括了加密的支付結(jié)果詳情。
- 加密不能保證通知請(qǐng)求來(lái)自微信。微信會(huì)對(duì)發(fā)送給商戶的通知進(jìn)行簽名，并將簽名值放在通知的HTTP頭Wechatpay-Signature。商戶應(yīng)當(dāng)驗(yàn)證簽名，以確認(rèn)請(qǐng)求來(lái)自微信，而不是其他的第三方。簽名驗(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ì)通過(guò)一定的策略定期重新發(fā)起通知，盡可能提高通知的成功率，但微信不保證通知最終能成功。（通知頻率為15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 總計(jì) 24h4m）。
特別提醒： 商戶系統(tǒng)對(duì)于開(kāi)啟結(jié)果通知的內(nèi)容一定要做簽名驗(yàn)證，并校驗(yàn)通知的信息是否與商戶側(cè)的信息一致，防止數(shù)據(jù)泄露導(dǎo)致出現(xiàn)“假通知”，造成資金損失
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 支付結(jié)果通知支付通知API接口文檔。
# 3.2.4. 【服務(wù)端】查詢訂單
步驟說(shuō)明： 當(dāng)商戶后臺(tái)、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常，商戶系統(tǒng)最終未接收到支付通知時(shí)，商戶可通過(guò)查詢訂單接口核實(shí)訂單支付狀態(tài)。
注意
查詢訂單可通過(guò)微信支付訂單號(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)單或撤銷(xiāo)接口API之前，需確認(rèn)支付狀態(tài)。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 微信支付訂單號(hào)/商戶訂單號(hào)接口文檔。
# 3.2.5. 【服務(wù)端】關(guān)閉訂單
步驟說(shuō)明： 當(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)單沒(méi)有時(shí)間限制，建議在訂單生成后間隔幾分鐘（最短5分鐘）再調(diào)用關(guān)單接口，避免出現(xiàn)訂單狀態(tài)同步不及時(shí)導(dǎo)致關(guān)單失敗。
- 已支付成功的訂單不能關(guān)閉。
示例代碼：
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 關(guān)閉訂單接口文檔
# 3.2.6. 【服務(wù)端】申請(qǐng)交易賬單
步驟說(shuō)明： 微信支付按天提供交易賬單文件，商戶可以通過(guò)該接口獲取賬單文件的下載地址。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 申請(qǐng)交易賬單接口文檔
# 3.2.7. 【服務(wù)端】下載賬單
步驟說(shuō)明： 過(guò)申請(qǐng)交易賬單接口獲取到賬單下載地址（download_url）后，再通過(guò)該接口獲取到對(duì)應(yīng)的賬單文件，文件內(nèi)包含交易相關(guān)的金額、時(shí)間、營(yíng)銷(xiāo)等信息，供商戶核對(duì)訂單、退款、銀行到賬等情況。
注意
- 賬單文件的下載地址的有效時(shí)間為30s。
- 強(qiáng)烈建議商戶將實(shí)際賬單文件的哈希值和之前從接口獲取到的哈希值進(jìn)行比對(duì)，以確認(rèn)數(shù)據(jù)的完整性。
- 該接口響應(yīng)的信息請(qǐng)求頭中不包含微信接口響應(yīng)的簽名值，因此需要跳過(guò)驗(yàn)簽的流程。
- 微信在次日9點(diǎn)啟動(dòng)生成前一天的對(duì)賬單，建議商戶10點(diǎn)后再獲取。
更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 下載賬單接口文檔。
# 4. 常見(jiàn)問(wèn)題
# Q：獲取OpenID接口報(bào)“此公眾號(hào)并沒(méi)有這些scope的權(quán)限，錯(cuò)誤碼10005”，如下圖所示
A：請(qǐng)按以下步驟進(jìn)行排查：
- 建議檢查一下公眾號(hào)的功能。比如是不是在訂閱號(hào)/未認(rèn)證的公眾號(hào)里面嘗試調(diào)用認(rèn)證服務(wù)號(hào)的功能。
- 確認(rèn)AppID是否認(rèn)證過(guò)期或者AppID填寫(xiě)錯(cuò)誤。
- 請(qǐng)嘗試使用snsapi_userinfo的授權(quán)登錄方式。
# Q：JSAPI調(diào)起支付接口報(bào)“商家暫時(shí)沒(méi)有此類(lèi)交易權(quán)限，請(qǐng)聯(lián)系商家客服”
A：請(qǐng)按以下步驟進(jìn)行排查：
- 請(qǐng)檢查你的下單接口是否指定了支付用戶的身份，該功能需單獨(dú)開(kāi)通指定身份支付權(quán)限方可使用。
- 請(qǐng)確認(rèn)你使用的商戶號(hào)是否有jsapi支付的權(quán)限，可登錄商戶平臺(tái)-產(chǎn)品中心查看。
# Q：JSAPI調(diào)起支付接口報(bào)“當(dāng)前頁(yè)面的URL未注冊(cè)”
A：請(qǐng)檢查下單接口中使用的商戶號(hào)是否在服務(wù)商平臺(tái) (opens new window)配置了對(duì)應(yīng)的支付目錄，可參考“設(shè)置支付目錄”章節(jié)說(shuō)明。
# Q：獲取OpenID接口報(bào)“redirect_url域名與后臺(tái)配置不一致，錯(cuò)誤碼：10003”
A：請(qǐng)按以下步驟進(jìn)行排查：
- 本錯(cuò)誤是公眾號(hào)獲取OpenID接口報(bào)的錯(cuò)誤，可參考文檔檢查是否符合開(kāi)發(fā)規(guī)范：網(wǎng)頁(yè)授權(quán) (opens new window)
- 檢查下單接口傳的AppID與獲取OpenID接口的AppID是否同一個(gè)（需一致）。
- 檢查AppID對(duì)應(yīng)的公眾號(hào)后臺(tái) (opens new window)，是否配置的授權(quán)域名和獲取OpenID的域名一致。授權(quán)域名配置路徑：【公眾平臺(tái) (opens new window)-> 設(shè)置-> 公眾號(hào)設(shè)置-> 功能設(shè)置–> 網(wǎng)頁(yè)授權(quán)域名】。
# Q：JSAPI調(diào)起支付接口報(bào)“該商戶暫不支持通過(guò)外部拉起微信完成支付”
A：JSAPI支付只能從微信瀏覽器內(nèi)發(fā)起支付請(qǐng)求。
