# 1. 接口規(guī)則

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

# 2. 開發(fā)準備

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

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

測試步驟：

1、根據自身開發(fā)語言，選擇對應的開發(fā)庫并構建項目，具體配置請參考下面鏈接的詳細說明：

• wechatpay-java (opens new window)（推薦）、wechatpay-apache-httpclient (opens new window)，適用于Java開發(fā)者。
  • 注：當前開發(fā)指引接口JAVA示例代碼采用wechatpay-apache-httpclient版本。
• wechatpay-php (opens new window)（推薦）、wechatpay-guzzle-middleware (opens new window)，適用于PHP開發(fā)者。
  • 注：當前開發(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后，可根據下面每個接口的示例代碼替換相關參數(shù)后進行快速測試。
• 開發(fā)者如果想詳細了解簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實現(xiàn)，可閱讀下面的詳細說明：

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

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

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

# 2.2.1. 注冊App

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

1. 登錄微信開放平臺 (opens new window)，進入【管理中心 → 移動應用 → 創(chuàng)建移動應用】；

   

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

   

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

   

   • Android應用包名和簽名的相關說明，參考下方【2.2.3. Android開發(fā)要點說明】。

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

   

5. 獲取到App的AppID后，需要將該AppID與商戶的收款mch_id進行綁定，商戶可登錄商戶平臺后前往【產品中心 -> AppID賬號管理】界面中進行AppID的綁定及管理，界面如圖所示：

   

# 2.2.2. iOS開發(fā)要點說明

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

由于蘋果公司在iOS13系統(tǒng)回收了查詢 App bundleID 的能力，導致微信無法保證授權憑證能正確返回給AppID對應的應用。為此，微信支付強烈要求所有商戶盡快升級到OpenSDK1.8.6，并讓用戶及時更新App，否則安全風險將一直存在。謝謝配合！

詳細OpenSDK升級指引請參見：OpenSDK升級指引 (opens new window)

• 開發(fā)配置：

以下項目開發(fā)環(huán)境以Xcode6.0，運行環(huán)境為IOS7.0為例，說明其開發(fā)中需要的操作

# 一、項目設置AppID

商戶在微信開放平臺申請開發(fā)App應用后，微信開放平臺會生成App的唯一標識AppID。在Xcode中打開項目，設置項目屬性中的URL Schemes為您的AppID。如圖標紅位置所示

# 二、注冊AppID

商戶App工程中引入微信lib庫和頭文件，調用API前，需要先向微信注冊您的AppID，代碼如下：

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

# 2.2.3. Android開發(fā)要點說明

# 1、后臺設置

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

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

應用簽名：根據項目的應用包名和編譯使用的keystore，可由簽名工具生成一個32位的md5串，在調試的手機上安裝簽名工具后，運行可生成應用簽名串，如圖8.9所示，綠色串即應用簽名。

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

# 2、注冊AppID

商戶App工程中引入微信JAR包，調用API前，需要先向微信注冊您的AppID，代碼如下：

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

# 3. 快速接入

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

重點步驟說明：

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

商戶調用App下單API后，分正常返回和異常返回情況：

• 正常返回：返回prepay_id，商戶可根據返回的prepay_id來生成調用OpenSDK的簽名以執(zhí)行下一步。
• 異常返回：返回HTTP code或錯誤碼，商戶可根據HTTP code列表 或錯誤碼說明來排查原因并執(zhí)行下一步操作。

步驟8： 商戶通過App調起支付OpenSDK調起微信支付，發(fā)起支付請求，有關OpenSDK調起支付的詳細說明，請參考iOS開發(fā)要點說明的說明

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

我們通過以下接口將用戶確認訂單信息回調通知給商戶系統(tǒng)：

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

方法二： 當因網絡抖動或本身notify_url存在問題等原因，導致無法接收到回調通知時，商戶也可主動調用查詢訂單API 查詢訂單API來獲取訂單狀態(tài)。

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

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

# 3.2.1. 【服務端】App下單

步驟說明：用戶在商戶App內完成商戶選擇后進入支付頁面，商戶需要通過后端請求該App下單API來獲取預支付ID。

重要入參說明：

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

更多參數(shù)、響應詳情及錯誤碼請參見App下單API接口文檔。

# 3.2.2. 【客戶端】OpenSDK調起支付

步驟說明： 通過App下單API成功獲取 預支付交易會話標識（prepay_id） 后，需要通過OpenSDK來調起微信支付收銀臺

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

重要入參說明：

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

paySign生成規(guī)則、響應詳情及錯誤碼請參見App調起支付接口文檔。

# iOS SDK調用說明

# 一、拉起支付

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

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結果回調

按照微信SDK Sample，在類實現(xiàn)onResp函數(shù)，支付完成后，微信App會返回到商戶App并回調onResp函數(shù)，開發(fā)者需要在該函數(shù)中接收通知，判斷返回錯誤碼。如果支付成功則去后臺查詢支付結果再展示用戶實際支付結果。注意一定不能以客戶端返回作為用戶支付的結果，應以服務器端接收的支付通知或查詢API返回的結果為準。

代碼示例如下：

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

回調中errCode值列表：

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

# Android SDK調用說明

# 一、SDK拉起支付

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

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);

# 二、支付結果回調

參照微信SDK Sample，在商戶包名.wxapi包路徑中實現(xiàn)WXPayEntryActivity類(包名或類名不一致會造成無法回調)，在WXPayEntryActivity類中實現(xiàn)onResp函數(shù)，支付完成后，微信App會返回到商戶App并回調onResp函數(shù)，開發(fā)者需要在該函數(shù)中接收通知，判斷返回錯誤碼。 如果支付成功則去后臺查詢支付結果再展示用戶實際支付結果。注意一定不能以客戶端返回作為用戶支付的結果，應以服務器端的接收的支付通知或查詢API返回的結果為準。

代碼示例如下：

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}

回調中errCode值列表：

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

# 3.2.3.【服務端】接收支付結果通知

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

更多參數(shù)、響應詳情及錯誤碼請參見 支付結果通知 接口文檔。

# 3.2.4. 【服務端】查詢訂單

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

示例代碼(通過微信訂單號查詢)：

更多參數(shù)、響應詳情及錯誤碼請參見 微信支付訂單號/商戶訂單號接口文檔。

# 3.2.5. 【服務端】關閉訂單

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

更多參數(shù)、響應詳情及錯誤碼請參見 關閉訂單接口文檔。

# 3.2.6. 【服務端】申請交易賬單

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

更多參數(shù)、響應詳情及錯誤碼請參見 申請交易賬單支付通知API接口文檔

# 3.2.7. 【服務端】下載賬單

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

更多參數(shù)、響應詳情及錯誤碼請參見 下載賬單支付通知API接口文檔。

# 4. 常見問題

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

A：請按以下幾點進行排查：

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

2. 查看調用SDK簽名是否正確，請注意以下幾點：

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

3. 檢查客戶端調用sendReq（PayReq）對象賦值的正確性（必要時讓商戶提供數(shù)據），若通過異步獲取到后臺數(shù)據，比如data對象是通過異步請求得到的對象：request.AppID = data.AppID; 實際AppID屬性值為空；

4. 檢查對應的開發(fā)配置，包括iOS的AppID配置，Android的包名及包簽名設置。

# Q：App調用“喚起支付API”返回：商戶支付下單ID非法

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

# Q：服務商模式下，調用App下單接口，返回“特殊子商戶未授權的產品權限”

A：App支付需要進行單獨的授權開通才可使用，請前往服務商平臺子商戶管理中找到對應的子商戶授權服務商App支付權限。

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

A：在調用App下單接口前，需保證子商戶號與子商戶App的AppID存在綁定關系，請服務商前往服務商平臺的子商戶管理頁面中操作綁定。