轉載自:https://docs.open.alipay.com/204/105297/
本文檔展示了如何從零開始,使用螞蟻金服開放平台服務端SDK快速接入App支付産品,完成與支付寶對接的部分。
注意: 文檔中的代碼示例和Demo是用來闡述API基本使用方法的,僅針對大衆場景。供ISV參考,特殊情況還請ISV自行擴充,確定符合自身業務需求。
支付産品全面更新,若您使用的是老接口,請移步老版本移動支付文檔。
若您希望從移動支付老版本更新為APP支付新版本,請參考以下步驟完成APP支付新版本的接入工作。若想了解更多關于新版本的更新改造内容,可參考移動支付與APP支付對比。
第一步:建立應用并擷取APPID
要在您的應用中接入支付寶App支付能力,需要通過建立應用的方式接入螞蟻相關接口并進行開發,基于對行業及業務場景痛點的了解,創造能夠滿足市場需要的解決方案,以應用的形式服務使用者。
若還未成為開放平台的入駐服務商或者商戶, 請完成入駐指引。入駐完成後,您需要去螞蟻金服開放平台(open.alipay.com),在開發者中心中建立您的應用,會為您生成應用唯一辨別(APPID),并且可以申請開通開放産品使用權限,通過APPID您的應用才能調用開放産品的接口能力。需要詳細了解開放平台建立應用步驟請參考《開放平台應用建立指南》。
在建立應用後即生成應用的辨別APPID,使用支付寶賬号登入開放平台後,在“我的應用”中按下圖方式檢視APPID。
![](https://img.laitimes.com/img/9ZDMuAjOiMmIsIjOiQnIsIyZuBnL5gjMlhTOyQmYmVDO2kjMxUWZhRDM1QmY1EzYxMTMxAzLcNXZslmZvw1YpxmY1B3LctmchxWerN3LcN3b69CXt92YuMHdjVmai9WehBXasFmL3d2Lc9CX6MHc0RHaiojIsJye.png)
第二步:配置應用
添加app支付功能
應用建立完成後,需要給應用添加App支付功能,這樣就可以在你的應用裡使用App支付能力。此時該應用為開發中狀态,隻能在沙箱環境下進行調試。應用開發完成後,請開發者自行進行驗收和安全性檢查(安全性檢查可參考《開放平台第三方應用安全開發指南》),驗收檢查完成後可申請上線。應用申請上線後,會同時申請此清單的功能,接口即生效,這個狀态下的應用能夠調用生産環境的接口。
開始添加
簽約
在使用這些能力的時候,需要在開放平台裡進行簽約,這時候約定的合同就生效了。也可以代替商戶簽約。
開始簽約
配置密鑰
為了保證交易雙方(商戶和支付寶)的身份和資料安全,開發者在調用接口前,需要配置雙方密鑰,對交易資料進行雙方校驗。
1、了解下支付寶密鑰處理體系:
2、密鑰包含:
應用公鑰:由商戶自己生成的RSA公鑰(與應用私鑰必須比對),商戶需上傳應用公鑰到支付寶開放平台,以便支付寶使用該公鑰驗證該交易是否是商戶發起的。
應用私鑰:由商戶自己生成的RSA私鑰(與應用公鑰必須比對),商戶開發者使用應用私鑰對請求字元串進行加簽。
支付寶公鑰:支付寶的RSA公鑰,商戶使用該公鑰驗證該結果是否是支付寶傳回的。
生成密鑰後在開放平台開發者中心進行密鑰配置,配置完成後可以擷取支付寶公鑰。具體方法流程請參見上傳應用公鑰并擷取支付寶公鑰。
3、配置生成的密鑰等應用資訊。配置的詳細步驟請參考《配置應用環境》。
注:簽名驗簽常見問題排查
支付寶開放平台SDK封裝了簽名和驗簽過程,隻需配置賬号及密鑰參數,強烈建議使用。更多簽名問題的自助排查流程,可以參考支付寶驗簽專區的未使用開放平台SDK的自助排查流程。關于同步通知和異步通知的驗簽規則,可參考驗簽教程。
更多關于簽名教程和簽名工具下載下傳等問題,請參見簽名專區。
第三步:內建和開發
接入移動支付需要內建兩個SDK,用戶端SDK需要內建在商戶自己的APP中,用于喚起支付寶APP并發送交易資料,并在支付寶APP傳回商戶APP時獲得支付結果。服務端SDK需要商戶內建在自己的服務端系統中,用于協助解析并驗證用戶端同步傳回的支付結果和異步通知。
開始內建和開發前
在開始內建和開發前,首先了解一下常用的接入方式和架建構議:
其次,為了保證交易安全,支付寶采用了一系列的安全手段:
- 采用HTTPS協定傳輸交易資料,防止資料被截獲,解密。
- 采用RSA非對稱密鑰,明确交易雙方的身份,保證交易主體的正确性和唯一性
了解更多的安全設計指南。
如何內建用戶端SDK
在內建App支付能力時,提供主流移動平台的App提供內建方式。
下載下傳用戶端SDK
更多內建說明參見用戶端內建說明。
如何內建服務端SDK
為了幫助開發者調用開放接口,我們提供了開放平台服務端DEMO&SDK,包含JAVA、PHP和.NET三語言版本,封裝了簽名&驗簽、HTTP接口請求等基礎功能(下單請求參數orderStr在服務端SDK封裝,用戶端SDK直接使用)。強烈建議先下載下傳對應語言版本的SDK并引入您的開發工程進行快速接入。
SDK調用前需要進行初始化,代碼示例如下:
AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);
關鍵參數說明:
配置參數 | 示例值解釋 | 擷取方式/示例值 |
---|---|---|
URL | 支付寶網關(固定) | https://openapi.alipay.com/gateway.do |
APP_ID | APPID即建立應用後生成 | 擷取見上面建立應用并擷取APPID |
APP_PRIVATE_KEY | 開發者應用私鑰,由開發者自己生成 | 擷取見上面配置密鑰 |
FORMAT | 參數傳回格式,隻支援json | json(固定) |
CHARSET | 請求和簽名使用的字元編碼格式,支援GBK和UTF-8 | 開發者根據實際工程編碼配置 |
ALIPAY_PUBLIC_KEY | 支付寶公鑰,由支付寶生成 | 擷取詳見上面配置密鑰 |
SIGN_TYPE | 商戶生成簽名字元串所使用的簽名算法類型,目前支援RSA2和RSA,推薦使用RSA2 | RSA2 |
接下來,就可以用alipayClient來調用具體的API了。alipayClient隻需要初始化一次,後續調用不同的API都可以使用同一個alipayClient對象。
TIPS:App支付不支援第三方授權,不能代商家發起請求。
第四步:調用接口
為了避免線上上生産環境聯調過程中遇到問題,建議在沙箱環境中聯調通過後再線上上生産環境進行聯調,具體操作步驟見沙箱聯調指南。如果需要線上上調用接口,需要參考下面第六步:應用上線後再進行接口調用,不然會報出“無權限錯誤”。
系統互動流程:
如圖,以Android平台為例:
圖中虛線辨別商戶鍊路,實線辨別支付寶鍊路。
第4步:調用支付接口:此消息就是本接口所描述的支付寶用戶端SDK提供的支付對象PayTask,将商戶簽名後的訂單資訊傳進payv2方法喚起支付寶收銀台,交易資料格式具體參見請求參數說明。
第5步:支付請求:支付寶用戶端SDK将會按照商戶用戶端提供的請求參數發送支付請求。
第8步:接口傳回支付結果:商戶用戶端在第4步中調用的支付接口,會傳回最終的支付結果(即同步通知),參見用戶端同步傳回。
第13步:使用者在支付寶APP或H5收銀台完成支付後,會根據商戶在手機網站支付API中傳入的前台回跳位址return_url自動跳轉回商戶頁面,同時在URL請求中附帶上支付結果參數。同時,支付寶還會根據原始支付API中傳入的異步通知位址notify_url,通過POST請求的形式将支付結果作為參數通知到商戶系統,詳情見支付結果異步通知。
除了正向支付流程外,支付寶也提供交易查詢、關閉、退款、退款查詢以及對賬等配套API。
特别注意:
- 構造交易資料并簽名必須在商戶服務端完成,商戶的應用私鑰絕對不能儲存在商戶APP用戶端中,也不能從服務端下發。
- 同步傳回的資料,隻是一個簡單的結果通知,商戶确定該筆交易付款是否成功需要依賴服務端收到支付寶異步通知的結果進行判斷。
- 商戶系統接收到通知以後,必須通過驗簽(驗證通知中的sign參數)來確定支付通知是由支付寶發送的。建議使用支付寶提供的SDK來完成,詳細驗簽規則參考異步通知驗簽。
使用SDK快速接入
App支付API必須通過支付寶提供的移動端SDK來調用。
交易操作
1.交易查詢接口alipay.trade.query:
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); //獲得初始化的AlipayClient
AlipayTradeQueryRequest request = new AlipayTradeQueryRequest();//建立API對應的request類
request.setBizContent("{" +
" \"out_trade_no\":\"20150320010101001\"," +
" \"trade_no\":\"2014112611001004680073956707\"" +
" }");//設定業務參數
AlipayTradeQueryResponse response = alipayClient.execute(request);//通過alipayClient調用API,獲得對應的response類
System.out.print(response.getBody());
//根據response中的結果繼續業務邏輯處理
關鍵入參:
參數名稱 | 參數說明 |
---|---|
out_trade_no | 支付時傳入的商戶訂單号,與trade_no必填一個 |
trade_no | 支付時傳回的支付寶交易号,與out_trade_no必填一個 |
關鍵出參:
參數名稱 | 參數說明 |
---|---|
trade_no | 支付寶28位交易号 |
out_trade_no | 支付時傳入的商戶訂單号 |
trade_status | 交易目前狀态 |
2.交易退款接口alipay.trade.refund:
商戶由于業務原因如金額錯誤、使用者退貨、對賬不平等情況可能需要退款,退款的途徑按照支付途徑原路傳回。支付管道為花呗、餘額等退款即時到賬。銀行卡的退款時間以銀行退款時間為準,一般情況下2小時内可到賬。可在商戶門戶(b.alipay.com)中退款;也可使用交易成功的商戶訂單号或支付寶交易号進行退款 , 支援全額和部分退款,其過程如下圖所示:
退款接口調用示例如下:
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); //獲得初始化的AlipayClient
AlipayTradeRefundRequest request = new AlipayTradeRefundRequest();//建立API對應的request類
request.setBizContent("{" +
" \"out_trade_no\":\"20150320010101001\"," +
" \"trade_no\":\"2014112611001004680073956707\"," +
" \"out_request_no\":\"1000001\"," +
" \"refund_amount\":\"1\"" +
" }");//設定業務參數
AlipayTradeRefundResponse response = alipayClient.execute(request);//通過alipayClient調用API,獲得對應的response類
System.out.print(response.getBody());
// 根據response中的結果繼續業務邏輯處理
關鍵入參:
參數名稱 | 參數說明 |
---|---|
out_trade_no | 支付時傳入的商戶訂單号,與trade_no必填一個 |
trade_no | 支付時傳回的支付寶交易号,與out_trade_no必填一個 |
out_request_no | 本次退款請求流水号,部分退款時必傳 |
refund_amount | 本次退款金額 |
關鍵出參:
參數名稱 | 參數說明 |
---|---|
refund_fee | 該筆交易已退款的總金額 |
3.查詢對賬單下載下傳位址接口alipay.data.dataservice.bill.downloadurl.query:
為了保障交易的正确性,支付寶提供了交易賬單資料提供給商戶對賬,對賬說明。
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); //獲得初始化的AlipayClient
AlipayDataDataserviceBillDownloadurlQueryRequest request = new AlipayDataDataserviceBillDownloadurlQueryRequest();//建立API對應的request類
request.setBizContent("{" +
" \"bill_type\":\"trade\"," +
" \"bill_date\":\"2016-04-05\"" +
" }");//設定業務參數
AlipayDataDataserviceBillDownloadurlQueryResponse response = alipayClient.execute(request);
System.out.print(response.getBody());
//根據response中的結果繼續業務邏輯處理
關鍵入參:
參數名稱 | 參數說明 |
---|---|
bill_type | 固定傳入trade |
bill_date | 需要下載下傳的賬單日期,最晚是當期日期的前一天 |
關鍵出參:
參數名稱 | 參數說明 |
---|---|
bill_download_url | 賬單檔案下載下傳位址,30秒有效 |
下載下傳賬單檔案:
//将接口傳回的對賬單下載下傳位址傳入urlStr
String urlStr = "http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&userId=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X";
//指定希望儲存的檔案路徑
String filePath = "/Users/fund_bill_20160405.csv";
URL url = null;
HttpURLConnection httpUrlConnection = null;
InputStream fis = null;
FileOutputStream fos = null;
try {
url = new URL(urlStr);
httpUrlConnection = (HttpURLConnection) url.openConnection();
httpUrlConnection.setConnectTimeout( * );
httpUrlConnection.setDoInput(true);
httpUrlConnection.setDoOutput(true);
httpUrlConnection.setUseCaches(false);
httpUrlConnection.setRequestMethod("GET");
httpUrlConnection.setRequestProperty("Charsert", "UTF-8");
httpUrlConnection.connect();
fis = httpUrlConnection.getInputStream();
byte[] temp = new byte[];
int b;
fos = new FileOutputStream(new File(filePath));
while ((b = fis.read(temp)) != -) {
fos.write(temp, , b);
fos.flush();
}
} catch (MalformedURLException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} finally {
try {
fis.close();
fos.close();
httpUrlConnection.disconnect();
} catch (NullPointerException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}
}
第五步:調試應用
支付能力直接涉及到交易與資金,為了友善開放者調試支付能力,我們已經準備好沙箱環境,包括沙箱環境賬号和沙箱版支付寶錢包,這樣就可以在沙箱環境調試了。具體操作步驟見沙箱聯調指南。
第六步:上線應用
商戶本身應用上線時候,也要把支付寶開放平台的應用上線。