# 1. 接口規(guī)則

為了在保證支付安全的前提下，帶給商戶簡單、一致且易用的開發(fā)體驗(yàn)，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請參考APIv3接口規(guī)則。

# 2. 開發(fā)準(zhǔn)備

# 2.1. 搭建和配置開發(fā)環(huán)境

為了幫助開發(fā)者調(diào)用開放接口，我們提供了JAVA、PHP、GO三種語言版本的開發(fā)庫，封裝了簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳 等基礎(chǔ)功能（更多語言版本的開發(fā)庫將在近期陸續(xù)提供）。

測試步驟：

1、根據(jù)自身開發(fā)語言，選擇對應(yīng)的開發(fā)庫并構(gòu)建項(xià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、基于接口的示例代碼，替換請求參數(shù)后可發(fā)起測試。

說明：

• 上面的開發(fā)庫為微信支付官方開發(fā)庫，其它沒有審核或者控制下的第三方工具和庫，微信支付不保證它們的安全性和可靠性。通過包管理工具引入SDK后，可根據(jù)下面每個(gè)接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測試。
• 開發(fā)者如果想詳細(xì)了解簽名生成、簽名驗(yàn)證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實(shí)現(xiàn)，可閱讀下面的詳細(xì)說明：

1. 簽名生成
2. 簽名驗(yàn)證
3. 敏感信息加解密
4. merchantPrivateKey（私鑰）
5. wechatpayCertificates（平臺(tái)證書）
6. APIV3Key（V3 key）

• 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔。

# 2.2. 業(yè)務(wù)開發(fā)配置

合單支付目前支持在微信外H5、App、JSAPI、小程序、Native掃碼5個(gè)場景使用，下面為你介紹JSAPI場景開發(fā)配置。

# 2.2.1. 設(shè)置支付授權(quán)目錄

1. 支付授權(quán)目錄說明：

   • 商戶最后請求拉起微信支付收銀臺(tái)的頁面地址我們稱之為“支付目錄”，例如：https://www.weixin.com/pay.php。
   • 商戶實(shí)際的支付目錄必須和在微信支付商戶平臺(tái)設(shè)置的一致，否則會(huì)報(bào)錯(cuò)“當(dāng)前頁面的URL未注冊：”

2. 支付授權(quán)目錄設(shè)置說明：

   登錄微信支付【商戶平臺(tái) (opens new window)->產(chǎn)品中心->開發(fā)配置】，設(shè)置后一般5分鐘內(nèi)生效。

   

3. 支付授權(quán)目錄校驗(yàn)規(guī)則說明：

   • 如果支付授權(quán)目錄設(shè)置為頂級域名（例如：https://www.weixin.com/ ），那么只校驗(yàn)頂級域名，不校驗(yàn)后綴；
   • 如果支付授權(quán)目錄設(shè)置為多級目錄，就會(huì)進(jìn)行全匹配，例如設(shè)置支付授權(quán)目錄為 https://www.weixin.com/abc/123/，則實(shí)際請求頁面目錄不能為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支付時(shí)，在JSAPI下單接口中要求必傳用戶OpenID，而獲取OpenID則需要您在公眾平臺(tái)設(shè)置獲取OpenID的域名，只有被設(shè)置過的域名才是一個(gè)有效的獲取OpenID的域名，否則將獲取失敗。具體配置頁見下圖。

授權(quán)域名設(shè)置說明：登錄【微信公眾平臺(tái) (opens new window)-->公眾號設(shè)置】。

# 3. 快速接入

# 3.1. 業(yè)務(wù)流程圖

業(yè)務(wù)流程時(shí)序圖如下。

重點(diǎn)步驟說明：

步驟1：用戶在商戶側(cè)發(fā)起支付請求，商戶先通過后臺(tái)接口合單下單-JSAPI接口創(chuàng)建合單支付訂單。

步驟2：商戶再根據(jù)用戶發(fā)起支付請求的具體場景通過合單下單-JSAPI頁面調(diào)起微信支付收銀臺(tái)，完成支付請求。

步驟3：用戶支付成功后，商戶可接收到支付結(jié)果回調(diào)通知。

步驟4：如果商戶長時(shí)間未收到回調(diào)通知，可通過合單查詢訂單接口主動(dòng)查詢訂單支付狀態(tài)。

# 3.2. API接入（含示例代碼）

文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入商家券產(chǎn)品，完成與微信支付對接的部分。

# 3.2.1. 【服務(wù)端】合單下單-JSAPI

步驟說明：用戶在商戶側(cè)選擇商品下單購買時(shí)，商戶系統(tǒng)先調(diào)用該接口在微信支付服務(wù)后臺(tái)生成預(yù)支付交易單，然后使用我們提供的客戶端方法（下文介紹）調(diào)起微信支付收銀臺(tái)，即可完成支付。

示例代碼：

重要入?yún)⒄f明：

• out_trade_no：商戶系統(tǒng)內(nèi)部訂單號，可以是數(shù)字、大小寫字母以及特殊符號_-*的任意組合，且在同一個(gè)商戶號下唯一。
• description：商品描述。
• notify_url：支付回調(diào)通知URL，該地址必須為直接可訪問的URL，不允許攜帶查詢串。
• total：訂單總金額，單位為分。
• OpenID：OpenID是微信用戶在AppID下的唯一用戶標(biāo)識（AppID不同，則獲取到的OpenID就不同），可用于永久標(biāo)記一個(gè)用戶。OpenID獲取方式請參考以下文檔小程序獲取OpenID (opens new window)、公眾號獲取OpenID (opens new window)、App獲取OpenID (opens new window)。

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見合單下單-JSAPI。

# 3.2.2.【客戶端】JSAPI調(diào)起支付

步驟說明：通過合單下單API成功獲取預(yù)支付交易會(huì)話標(biāo)識（prepay_id）后，需要通過JSAPI調(diào)起支付API來調(diào)起微信支付收銀臺(tái)。

示例代碼：

1function onBridgeReady() {
2    WeixinJSBridge.invoke('getBrandWCPayRequest', {
3        "appId": "wx2421b1c4370ecxxx",      //公眾號ID，由商戶傳入
4        "timeStamp": "1395712654",   //時(shí)間戳，自1970年以來的秒數(shù)
5        "nonceStr": "e61463f8efa94090b1f366cccfbbb444",    //隨機(jī)串
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            // 使用以上方式判斷前端返回,微信團(tuán)隊(duì)鄭重提示：
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)詳情及錯(cuò)誤碼請參見JSAPI調(diào)起支付接口文檔。

# 3.2.3.【服務(wù)端】接收支付結(jié)果通知

步驟說明：當(dāng)用戶完成支付，微信會(huì)把相關(guān)支付結(jié)果將通過異步回調(diào)的方式通知商戶，商戶需要接收處理，并按文檔規(guī)范返回應(yīng)答。

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見支付結(jié)果通知API接口文檔。

# 3.2.4. 【服務(wù)端】合單查詢訂單

步驟說明：當(dāng)商戶后臺(tái)、網(wǎng)絡(luò)、服務(wù)器等出現(xiàn)異常，商戶系統(tǒng)最終未接收到支付結(jié)果通知時(shí)商戶可通過查詢訂單接口核實(shí)訂單支付狀態(tài)。

示例代碼：

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見合單查詢訂單接口文檔。

# 3.2.5. 【服務(wù)端】合單關(guān)閉訂單

步驟說明：當(dāng)商戶訂單支付失敗需要生成新單號重新發(fā)起支付，要對原訂單號調(diào)用關(guān)單，避免重復(fù)支付；系統(tǒng)下單后，用戶支付超時(shí)，系統(tǒng)退出不再受理，避免用戶繼續(xù)，請調(diào)用關(guān)單接口。

示例代碼：

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見合單關(guān)單API接口文檔。

# 3.2.6. 【服務(wù)端】申請交易賬單

步驟說明：微信支付按天提供交易賬單文件，商戶可以通過該接口獲取賬單文件的下載地址。

示例代碼：

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見申請交易賬單API接口文檔。

# 3.2.7. 【服務(wù)端】下載賬單

步驟說明：通過申請交易賬單接口獲取到賬單下載地址（download_url）后，再通過該接口獲取到對應(yīng)的賬單文件，文件內(nèi)包含交易相關(guān)的金額、時(shí)間、營銷等信息，供商戶核對訂單、退款、銀行到賬等情況。

示例代碼：

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請參見下載賬單API接口文檔。

# 4. 常見問題

問: 獲取OpenID接口報(bào)“此公眾號并沒有這些scope的權(quán)限，錯(cuò)誤碼10005”，如下圖所示。

答: 請按以下步驟進(jìn)行排查：

1. 建議檢查一下公眾號的功能。比如是不是在訂閱號/未認(rèn)證的公眾號里面嘗試調(diào)用認(rèn)證服務(wù)號的功能。
2. 確認(rèn)AppID是否認(rèn)證過期或者AppID填寫錯(cuò)誤。
3. 請嘗試使用snsapi_userinfo的授權(quán)登錄方式。

問: JSAPI調(diào)起支付接口報(bào)“商家暫時(shí)沒有此類交易權(quán)限，請聯(lián)系商家客服”。

答：請按以下步驟進(jìn)行排查：

1. 請檢查你的下單接口是否指定了支付用戶的身份，該功能需單獨(dú)開通指定身份支付權(quán)限方可使用
2. 請確認(rèn)你使用的商戶號是否有jsapi支付的權(quán)限，可登錄商戶平臺(tái)-產(chǎn)品中心查看

問：JSAPI調(diào)起支付接口報(bào)“當(dāng)前頁面的URL未注冊”。

答：請檢查下單接口中使用的商戶號是否在商戶平臺(tái) (opens new window)配置了對應(yīng)的支付目錄，可參考設(shè)置支付授權(quán)目錄章節(jié)說明。

問：獲取OpenID接口報(bào)“redirect_url域名與后臺(tái)配置不一致，錯(cuò)誤碼：10003”。

答：請按以下步驟進(jìn)行排查：

1. 本錯(cuò)誤是公眾號獲取OpenID接口報(bào)的錯(cuò)誤，可參考文檔檢查是否符合開發(fā)規(guī)范：網(wǎng)頁授權(quán) (opens new window)
2. 檢查下單接口傳的AppID與獲取OpenID接口的AppID是否同一個(gè)（需一致）。
3. 檢查AppID對應(yīng)的公眾號后臺(tái) (opens new window)，是否配置的授權(quán)域名和獲取OpenID的域名一致。授權(quán)域名配置路徑：【公眾平臺(tái) (opens new window)-> 設(shè)置-> 公眾號設(shè)置-> 功能設(shè)置–> 網(wǎng)頁授權(quán)域名】。

問：JSAPI調(diào)起支付接口報(bào)“該商戶暫不支持通過外部拉起微信完成支付”。

答：JSAPI支付只能從微信瀏覽器內(nèi)發(fā)起支付請求。