# 1. 接口規(guī)則

為了在保證支付安全的前提下，帶給商戶(hù)簡(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)建加載商戶(hù)私鑰、加載平臺(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ō)明：

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

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

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

# 2.2.1. 注冊(cè)App

App接入微信支付，需要先將商戶(hù)App在微信開(kāi)放平臺(tái)進(jìn)行注冊(cè)，登記App開(kāi)發(fā)參數(shù)以生成AppID。具體操作步驟如下：

1. 登錄微信開(kāi)放平臺(tái) (opens new window)，進(jìn)入【管理中心 → 移動(dòng)應(yīng)用 → 創(chuàng)建移動(dòng)應(yīng)用】；

   

2. 完成基本信息的錄入，商戶(hù)需要在本步驟提交App對(duì)應(yīng)的下載地址，應(yīng)用官網(wǎng)，應(yīng)用水印，icon等業(yè)務(wù)信息；

   

3. 完成平臺(tái)信息的錄入，商戶(hù)需要在本步驟提交App在Android及iOS端對(duì)應(yīng)的開(kāi)發(fā)參數(shù)，包括Android端應(yīng)用的包名，應(yīng)用簽名，iOS端應(yīng)用的bundle ID, universal link等；

   

   注意

   • Android應(yīng)用包名和簽名的相關(guān)說(shuō)明，參考“Andriod開(kāi)發(fā)要點(diǎn)說(shuō)明 (opens new window)”。

4. 以上信息全部提交完成后，即完成App的注冊(cè)，商戶(hù)可在【管理中心 → 移動(dòng)應(yīng)用】中，選擇具體的應(yīng)用查看其AppID及已獲得的接口能力；

   

5. 獲取到App的AppID后，需要將該AppID與商戶(hù)的收款mch_id進(jìn)行綁定，商戶(hù)可登錄商戶(hù)平臺(tái)后前往【產(chǎn)品中心 -> AppID賬號(hào)管理】界面中進(jìn)行AppID的綁定及管理，界面如圖所示：

   

# 2.2.2. iOS開(kāi)發(fā)要點(diǎn)說(shuō)明

• iOS系統(tǒng)OpenSDK升級(jí)指引

由于蘋(píng)果公司在iOS13系統(tǒng)回收了查詢(xún) App bundleID 的能力，導(dǎo)致微信無(wú)法保證授權(quán)憑證能正確返回給AppID對(duì)應(yīng)的應(yīng)用。為此，微信支付強(qiáng)烈要求所有商戶(hù)盡快升級(jí)到OpenSDK1.8.6，并讓用戶(hù)及時(shí)更新App，否則安全風(fēng)險(xiǎn)將一直存在。謝謝配合！

詳細(xì)OpenSDK升級(jí)指引請(qǐng)參見(jiàn)：OpenSDK升級(jí)指引 (opens new window)。

• 開(kāi)發(fā)配置：

以下項(xiàng)目開(kāi)發(fā)環(huán)境以Xcode6.0，運(yùn)行環(huán)境為IOS7.0為例，說(shuō)明其開(kāi)發(fā)中需要的操作

# 一、項(xiàng)目設(shè)置AppID

商戶(hù)在微信開(kāi)放平臺(tái)申請(qǐng)開(kāi)發(fā)App應(yīng)用后，微信開(kāi)放平臺(tái)會(huì)生成App的唯一標(biāo)識(shí)AppID。在Xcode中打開(kāi)項(xiàng)目，設(shè)置項(xiàng)目屬性中的URL Schemes為您的AppID。如圖標(biāo)紅位置所示。

# 二、注冊(cè)AppID

商戶(hù)App工程中引入微信lib庫(kù)和頭文件，調(diào)用API前，需要先向微信注冊(cè)您的AppID，代碼如下：

[WXApi registerApp：@"wxd930ea5d5a258f4f" withDescription：@"demo 2.0"];

# 2.2.3. Android開(kāi)發(fā)要點(diǎn)說(shuō)明

# 1、后臺(tái)設(shè)置

商戶(hù)在微信開(kāi)放平臺(tái)申請(qǐng)開(kāi)發(fā)應(yīng)用后，微信開(kāi)放平臺(tái)會(huì)生成App的唯一標(biāo)識(shí)AppID。由于需要保證支付安全，需要在開(kāi)放平臺(tái)綁定商戶(hù)應(yīng)用包名和應(yīng)用簽名，設(shè)置好后才能正常發(fā)起支付。設(shè)置界面在【開(kāi)放平臺(tái)】中的欄目【管理中心 / 修改應(yīng)用 / 修改開(kāi)發(fā)信息】里面，如圖紅框內(nèi)所示。

應(yīng)用包名：是在App項(xiàng)目配置文件AndroidManifest.xml中聲明的package值，例如上圖中的package="demo.wxpay.tenpay.com"。

應(yīng)用簽名：根據(jù)項(xiàng)目的應(yīng)用包名和編譯使用的keystore，可由簽名工具生成一個(gè)32位的md5串，在調(diào)試的手機(jī)上安裝簽名工具后，運(yùn)行可生成應(yīng)用簽名串，如圖8.9所示，綠色串即應(yīng)用簽名。

點(diǎn)擊下載簽名生成工具 (opens new window)

# 2、注冊(cè)AppID

商戶(hù)App工程中引入微信JAR包，調(diào)用API前，需要先向微信注冊(cè)您的AppID，代碼如下：

1final IWXAPI msgApi = WXAPIFactory.createWXAPI(context, null);
2// 將該app注冊(cè)到微信
3msgApi.registerApp("wxd930ea5d5a258f4f");

# 3. 快速接入

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

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

步驟3： 用戶(hù)下單發(fā)起支付，商戶(hù)可通過(guò)微信支付App下單API創(chuàng)建支付訂單。

商戶(hù)調(diào)用App下單API后，分正常返回和異常返回情況：

• 正常返回：返回prepay_id，商戶(hù)可根據(jù)返回的prepay_id來(lái)生成調(diào)用OpenSDK的簽名以執(zhí)行下一步。
• 異常返回：返回HTTP code或錯(cuò)誤碼，商戶(hù)可根據(jù)HTTP code列表 或錯(cuò)誤碼說(shuō)明來(lái)排查原因并執(zhí)行下一步操作。

步驟8： 商戶(hù)通過(guò)App調(diào)起支付OpenSDK調(diào)起微信支付，發(fā)起支付請(qǐng)求，有關(guān)OpenSDK調(diào)起支付的詳細(xì)說(shuō)明，請(qǐng)參考iOS開(kāi)發(fā)要點(diǎn)說(shuō)明部分的說(shuō)明

步驟15-19: 用戶(hù)支付成功后，商戶(hù)可通過(guò)以下兩種方式獲取訂單狀態(tài)。

我們通過(guò)以下接口將用戶(hù)確認(rèn)訂單信息回調(diào)通知給商戶(hù)系統(tǒng)：

方法一： 支付結(jié)果通知。用戶(hù)支付成功后，微信支付會(huì)將支付成功的結(jié)果以回調(diào)通知的形式同步給商戶(hù)，商戶(hù)的回調(diào)地址需要在調(diào)用App下單API時(shí)傳入notify_url參數(shù)。

方法二： 當(dāng)因網(wǎng)絡(luò)抖動(dòng)或本身notify_url存在問(wèn)題等原因，導(dǎo)致無(wú)法接收到回調(diào)通知時(shí)，商戶(hù)也可主動(dòng)調(diào)用查詢(xún)訂單API 查詢(xún)訂單API來(lái)獲取訂單狀態(tài)。

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

文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入支付有禮，完成與微信支付對(duì)接的部分。

# 3.2.1. 【服務(wù)端】App下單

步驟說(shuō)明： 用戶(hù)在商戶(hù)App內(nèi)完成商戶(hù)選擇后進(jìn)入支付頁(yè)面，商戶(hù)需要通過(guò)后端請(qǐng)求該App下單API來(lái)獲取預(yù)支付ID。

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

• out_trade_no：商戶(hù)系統(tǒng)內(nèi)部訂單號(hào)，只能是數(shù)字、大小寫(xiě)字母_-*且在同一個(gè)商戶(hù)號(hào)下唯一。
• description：商品描述。
• notify_url：支付回調(diào)通知URL，該地址必須為直接可訪(fǎng)問(wèn)的URL，不允許攜帶查詢(xún)串。
• total：訂單總金額，單位為分。

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

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

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

• 該步驟請(qǐng)使用開(kāi)放平臺(tái)的官方OpenSDK：
  • IOS OpenSDK下載地址 (opens new window)。
  • Android OpenSDK下載地址 (opens new window)。
• SDK的調(diào)用需要攜帶簽名（參與簽名的參數(shù)為：AppID、partnerid、prepayid、package、noncestr、timestamp，參數(shù)區(qū)分大小寫(xiě)）。

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

• package： 取固定值Sign=WXPay。
• signType： 該接口V3版本僅支持RSA。
• paySign： 簽名。

paySign生成規(guī)則、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn)App調(diào)起支付接口文檔。

# iOS SDK調(diào)用說(shuō)明

# 一、拉起支付

商戶(hù)服務(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]

# 二、SDK結(jié)果回調(diào)

按照微信SDK Sample，在類(lèi)實(shí)現(xiàn)onResp函數(shù)，支付完成后，微信App會(huì)返回到商戶(hù)App并回調(diào)onResp函數(shù)，開(kāi)發(fā)者需要在該函數(shù)中接收通知，判斷返回錯(cuò)誤碼， 如果支付成功則去后臺(tái)查詢(xún)支付結(jié)果再展示用戶(hù)實(shí)際支付結(jié)果。注意 一定不能以客戶(hù)端返回作為用戶(hù)支付的結(jié)果，應(yīng)以服務(wù)器端接收的支付通知或查詢(xún)API返回的結(jié)果為準(zhǔn)。

代碼示例如下：

1-(void)onResp：(BaseResp*)resp{
2if ([respisKindOfClass：[PayRespclass]]){
3    PayResp*response=(PayResp*)resp;
4    switch(response.errCode){
5                caseWXSuccess： //服務(wù)器端查詢(xún)支付通知或查詢(xún)API返回的結(jié)果再提示成功
6                          NSlog(@"支付成功");
7                break;
8                default：
9                          NSlog(@"支付失敗，retcode=%d",resp.errCode);
10                break;
11      }
12  }
13}

回調(diào)中errCode值列表：

名稱(chēng)	描述	解決方案
-2	用戶(hù)取消	無(wú)需處理。發(fā)生場(chǎng)景：用戶(hù)不支付了，點(diǎn)擊取消，返回App。
0	成功	展示成功頁(yè)面
-1	錯(cuò)誤	可能的原因：簽名錯(cuò)誤、未注冊(cè)AppID、項(xiàng)目設(shè)置AppID不正確、注冊(cè)的AppID與設(shè)置的不匹配、其他異常等。

# Android SDK調(diào)用說(shuō)明

# 一、SDK拉起支付

商戶(hù)服務(wù)器生成支付訂單，先調(diào)用App下單API生成預(yù)付單，獲取到prepay_id后將參數(shù)再次簽名傳輸給App發(fā)起支付。以下是調(diào)起微信支付的關(guān)鍵代碼：

1IWXAPI api;
2  PayReq request = new PayReq();
3  request.appId = "wxd930ea5d5a258f4f";  
4  request.partnerId = "1900000109"; 
5  request.prepayId= "1101000000140415649af9fc314aa427",;  
6  request.packageValue = "Sign=WXPay";
7  request.nonceStr= "1101000000140429eb40476f8896f4c9";
8  request.timeStamp= "1398746574";
9  request.sign= "7FFECB600D7157C5AA49810D2D8F28BC2811827B";
10  api.sendReq(request);

# 二、支付結(jié)果回調(diào)

參照微信SDK Sample，在商戶(hù)包名.wxapi包路徑中實(shí)現(xiàn)WXPayEntryActivity類(lèi)(包名或類(lèi)名不一致會(huì)造成無(wú)法回調(diào))，在WXPayEntryActivity類(lèi)中實(shí)現(xiàn)onResp函數(shù)，支付完成后，微信App會(huì)返回到商戶(hù)App并回調(diào)onResp函數(shù)，開(kāi)發(fā)者需要在該函數(shù)中接收通知，判斷返回錯(cuò)誤碼， 如果支付成功則去后臺(tái)查詢(xún)支付結(jié)果再展示用戶(hù)實(shí)際支付結(jié)果。注意一定不能以客戶(hù)端返回作為用戶(hù)支付的結(jié)果，應(yīng)以服務(wù)器端的接收的支付通知或查詢(xún)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值列表：

名稱(chēng)	描述	解決方案
0	成功	展示成功頁(yè)面
-1	錯(cuò)誤	可能的原因：簽名錯(cuò)誤、未注冊(cè)AppID、項(xiàng)目設(shè)置AppID不正確、注冊(cè)的AppID與設(shè)置的不匹配、其他異常等。
-2	用戶(hù)取消	無(wú)需處理。發(fā)生場(chǎng)景：用戶(hù)不支付了，點(diǎn)擊取消，返回App。

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

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

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

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

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

示例代碼(通過(guò)微信訂單號(hào)查詢(xún))：

更多參數(shù)、響應(yīng)詳情及錯(cuò)誤碼請(qǐng)參見(jiàn) 微信支付訂單號(hào)/商戶(hù)訂單號(hào)接口文檔。

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

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

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

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

步驟說(shuō)明： 微信支付按天提供交易賬單文件，商戶(hù)可以通過(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)等信息，供商戶(hù)核對(duì)訂單、退款、銀行到賬等情況。

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

# 4. 常見(jiàn)問(wèn)題

# Q：微信App支付，前端調(diào)起的時(shí)候返回errcode = -1該如何排查？

A：請(qǐng)按以下步驟進(jìn)行排查：

1. 查看App下單參數(shù)返回是否正常，是否有正確的在調(diào)用SDK前獲取了正確的prepay_id；

2. 查看調(diào)用SDK簽名是否正確，請(qǐng)注意以下幾點(diǎn)：

   • 參與簽名的參數(shù)名大小寫(xiě)一定要與文檔中保持一致；
   • App下單返回的簽名和調(diào)用SDK使用的簽名不是同一個(gè)，調(diào)用SDK需要單獨(dú)根據(jù)SDK參數(shù)生成簽名。

3. 檢查客戶(hù)端調(diào)用sendReq（PayReq）對(duì)象賦值的正確性（必要時(shí)讓商戶(hù)提供數(shù)據(jù)），若通過(guò)異步獲取到后臺(tái)數(shù)據(jù)，比如data對(duì)象是通過(guò)異步請(qǐng)求得到的對(duì)象：request.AppID = data.AppID; 實(shí)際AppID屬性值為空；

4. 檢查對(duì)應(yīng)的開(kāi)發(fā)配置，包括iOS的AppID配置，Android的包名及包簽名設(shè)置。

# Q：App調(diào)用“喚起支付API”返回：商戶(hù)支付下單ID非法

A：請(qǐng)確認(rèn)喚起支付參數(shù)字段名是否與文檔的一致。

# Q：服務(wù)商模式下，調(diào)用App下單接口，返回“特殊子商戶(hù)未授權(quán)的產(chǎn)品權(quán)限”

A：App支付需要進(jìn)行單獨(dú)的授權(quán)開(kāi)通才可使用，請(qǐng)前往服務(wù)商平臺(tái)子商戶(hù)管理中找到對(duì)應(yīng)的子商戶(hù)授權(quán)服務(wù)商App支付權(quán)限。

# Q：調(diào)用App下單接口，返回“sub_appid與sub_mch_id不匹配”

A：在調(diào)用App下單接口前，需保證子商戶(hù)號(hào)與子商戶(hù)App的AppID存在綁定關(guān)系，請(qǐng)服務(wù)商前往服務(wù)商平臺(tái)的子商戶(hù)管理頁(yè)面中操作綁定。