開發前的準備工作
1. 打開 https://open.unionpay.com/ ,后續說的文檔下載、FAQ查詢等都在這個平臺操作。
2. 下載規范和開發包。幫助中心-下載-產品接口規范-手機控件支付產品接口規范,幫助中心-下載-產品接口規范-手機控件支付產品技術開發包。
3. 開發人員都請先看下6.2的消費的交易流程。
4. 相關測試參數:
如果已簽約,有自己的測試商戶,則直接用自己的商戶號測試,測試證書開發包里都有。* 盡量用真實商戶號測試,防止有時候參數配錯能盡早發現。
如果沒有簽約,或者商戶號尚未分配,請在平臺里自行獲取商戶并且開交易權限,方法為:
a) 左上角注冊;
b) 登陸后右上角我的測試-測試參數
c) 我的測試-產品-選下自己集成的。
測試卡號信息:
借記卡:6226090000000048
手機號:18100000000
密碼:111101
短信驗證碼:123456
(短信驗證碼記得點下獲取驗證碼之后再輸入)
貸記卡:6226388000000095;
手機號:18100000000;
cvn2:248;
有效期:1219;
短信驗證碼:123456
(短信驗證碼記得點下獲取驗證碼之后再輸入)
SDK說明
商戶開發者在獲取到銀聯提供的開發包后請檢查SDK文件所在目錄upmp_iphone/paymentcontrol,以下部分提及的文件均在該目錄中。銀聯支付控件靜態庫,以下簡稱UPPaymentControl,包含以下兩個文件:
UPPaymentControl.h
libPaymentControl.a
接口說明
-
1、支付接口
- (BOOL)startPay:(NSString*)tn fromScheme:(NSString*)schemeStr mode:(NSString*)mode viewController:(UIViewController*)viewController
各個參數定義如下表:
-
2、檢查是否安裝銀聯App的接口
- (BOOL)isPaymentAppInstalled
此函數無傳入參數,主要功能檢測用戶手機上是否安裝銀聯支付的APP,當用戶手機上安裝了銀聯支付APP時候返回YES。
- 3、返回結果接口
- (void)handlePaymentResult:(NSURL*)url completeBlock:(UPPaymentResultBlock)completionBlock;
各參數定義如下表:
添加SDK包
使用UPPaymentControl需要將paymentcontrol/inc目錄下UPPaymentControl.h文件和paymentcontrol/libs目錄下的libPaymentControl.a文件添加到商戶應用的工程中,添加后如圖:
工程配置
1、使用UPPaymentControl需要添加CFNetwork.framework、SystemConfiguration.framework 、libz、libPaymentControl.a到工程中
2、在工程info.plist設置中添加一個URL Types回調協議(在UPPayDemo工程中使用“UPPayDemo”作為協議),用于在支付完成后返回商戶客戶端。
3、http請求設置
在Xcode7.0之后的版本中進行http請求時,需要在工程對應的plist文件中添加NSAppTransportSecurity Dictionary 并同時設置里面NSAllowsArbitraryLoads 屬性值為 YES
4、添加協議白名單
在Xcode7.0之后的版本中進行開發,需要在工程對應的plist文件中,添加LSApplicationQueriesSchemes Array并加入uppaysdk、uppaywallet、uppayx1、uppayx2、uppayx3五個item,具體設置可參考以下截圖:
或者直接添加如下代碼到plist文件中:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>uppaysdk</string>
<string>uppaywallet</string>
<string>uppayx1</string>
<string>uppayx2</string>
<string>uppayx3</string>
</array>
調用插件
在需要調用支付控件接口的代碼文件內引用頭文件UPPaymentControl.h。
(注意:如果工程的compile source as 選項的值不是Objective–C++,則引用此頭文件的文件類型都要改為.mm)
-
1、支付接口調用
商戶App從商戶服務器獲取tn,當tn不為空時,調用支付接口。//當獲得的tn不為空時,調用支付接口 if (tn != nil && tn.length > 0) { [[UPPaymentControl defaultControl]startPay:tn fromScheme:@"UPPayDemo" mode:self.tnMode viewController:self]; }
2、檢測是否已安裝銀聯App接口調用
if([[UPPaymentControl defaultControl] isPaymentAppInstalled])
{
//當判斷用戶手機上已安裝銀聯App,商戶客戶端可以做相應個性化處理
}
- 3、返回結果接口調用
支付控件結果處理函數handlePaymentResult: completeBlock:需要在工程AppDelegate文件的application: openURL: sourceApplication: annotation: 方法中進行調用。
支付控件結果處理函數handlePaymentResult: completeBlock:包含兩個參數,參數1url為支付結果串,由handlePaymentResult: completeBlock:方法解析url內容;參數2completionBlock為商戶APP定義的結果處理方法,包含兩個傳入參數code和data,其中code表示支付結果,取值為suceess,fail,cancel分別表示支付成功、支付失敗和支付取消,data表示結果簽名數據,商戶使用銀聯公鑰驗證結果真實性。
對于新增的簽名信息需注意以下幾點:
- 前臺返回的支付結果中包含銀聯簽名,要在商戶后臺對簽名進行校驗后才能展示結果。
- 前臺簽名使用的密鑰和算法與后臺結果中的簽名一致。
- 如果商戶APP在客戶端內進行簽名驗證,要自行實現簽名密鑰更新的機制,否則更換密鑰后會導致驗簽失敗。(不推薦)
- 商戶訂單是否成功支付應該以商戶后臺收到全渠道返回的支付結果為準,此處支付控件返回的結果僅作為參考。
調用支付接口后,結果處理方法示例代碼:
- (BOOL) application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
[[UPPaymentControl defaultControl] handlePaymentResult:url completeBlock:^(NSString *code, NSDictionary *data) {
//結果code為成功時,先校驗簽名,校驗成功后做后續處理
if([code isEqualToString:@"success"]) {
//數據從NSDictionary轉換為NSString
NSDictionary *data;
NSData *signData = [NSJSONSerialization dataWithJSONObject:data options:0 error:nil];
NSString *sign = [[NSString alloc] initWithData:signData encoding:NSUTF8StringEncoding];
//判斷簽名數據是否存在
if(data == nil) {
//如果沒有簽名數據,建議商戶app后臺查詢交易結果
return;
}
//驗簽證書同后臺驗簽證書
//此處的verify,商戶需送去商戶后臺做驗簽
if([self verify:sign]) {
//支付成功且驗簽成功,展示支付成功提示
}else {
//驗簽失敗,交易結果數據被篡改,商戶app后臺查詢交易結果
}
}else if([code isEqualToString:@"fail"]) {
//交易失敗
}else if([code isEqualToString:@"cancel"]) {
//交易取消
}
}];
return YES;
}
completeBlock中的NSDictionary *data結構如下:
sign —— 簽名后做Base64的數據
data —— 用于簽名的原始數據,結構如下:pay_result —— 支付結果success,fail,cancel
tn —— 訂單號
Data轉換為String后的示例如下:
"{"sign":"ZnZY4nqFGu/ugcXNIhniJh6UDVriWANlHtIDRzV9w120E6tUgpL9Z7jIFzWrSV73hmrkk8BZMXMc/9b8u3Ex1ugnZn0OZtWfMZk2I979dxp2MmOB+1N+Zxf8iHr7KNhf9xb+VZdEydn3Wc/xX/B4jncg0AwDJO/0pezhSZqdhSivTEoxq7KQTq2KaHJmNotPzBatWI5Ta7Ka2l/fKUv8zr6DGu3/5UaPqHhnUq1IwgxEWOYxGWQgtyTMo/tDIRx0OlXOm4iOEcnA9DWGT5hXTT3nONkRFuOSyqS5Rzc26gQE6boD+wkdUZTy55ns8cDCdaPajMrnuEByZCs70yvSgA==","data":"pay_result=success&tn=201512151321481233778"}"
老版控件用戶修改說明
添加SDK包
使用老版本銀聯支付控件的商戶請先將老版本銀聯支付控件從工程中刪除,再將新paymentcontrol/inc目錄下UPPaymentControl.h文件和paymentcontrol/libs目錄下libPaymentControl.a文件添加到商戶應用的工程中;添加后如圖:
工程配置
1、使用老版本銀聯支付控件的商戶請先將工程配置中老版支付控件對應的三方庫刪除,再添加CFNetwork.framework、SystemConfiguration.framework 、libPaymentControl.a、libz到工程中;添加后如下圖:
2、在工程info.plist設置中添加一個URL Types回調協議(在UPPayDemo工程中使用“UPPayDemo”作為協議),用于在支付控件完成支付后返回到商戶客戶端。
3、添加協議白名單
在工程對應的plist文件中,添加LSApplicationQueriesSchemes Array并加入uppaysdk、uppaywallet、uppayx1、uppayx2、uppayx3五個item,具體設置可參考以下截圖:
或者直接添加以下代碼到plist文件中:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>uppaysdk</string>
<string>uppaywallet</string>
<string>uppayx1</string>
<string>uppayx2</string>
<string>uppayx3</string>
</array>
接口說明和調用插件
請參考4.2接口說明和4.4調用插件說明。
常見問題總結
更多請參見https://open.unionpay.com幫助中心-FAQ
怎樣加-ObjC宏
選擇工程targets——》build settings ->Linking->other linker flags
編譯時提示Undefined for architecture XXX 錯誤
如:
1)由于支付控件使用到了C、C++和OC混編的情況,所以商戶工程引入UPPaymentControl.h頭文件以后可能會出現鏈接錯誤,這個時候可以通過以下三種方式解決:
① 將涉及到引用UPPaymentControl.h的源文件的后綴名都改為.mm;
② 如果商戶不想修改源文件的后綴名,可以在工程中添加一個空的繼承自NSObject的類,并將文件.m后綴名該改為.mm即可方法為new file->Objective-C class->類名自取->保存->修改后綴名為.mm;
③ 將工程的compile source as 選項的值設置為Objective–C++;
2)由于在UPPayDemo工程中添加了自定義的庫文件libPaymentControl.a
,當編譯Demo工程時,應該檢查工程設置Search Paths里的Framework Search Paths、Header Search Paths、Library Search Paths的路徑設置,看設置路徑是否正確,另外還要注意里邊是否多余一些不確定的路徑。
- 將xcode工程中Build Setting -> Apple LLVM compiler Language 標簽下的C++ Language Dialect 和 C++ Standard Library 屬性值修改為 Compiler Default如實在無法解決,嘗試添加-ObjC宏的地方修改為 -force_load+空格+控件路徑,如:-force_load $(PROJECT_DIR)/ libPaymentControl.a,如果還報錯,上下文應該會有libPaymentControl.a文件找不到異常,比如ld: file not found: /Users/apple/Desktop/Communication 2/ libPaymentControl.a
clang: error: linker command failed with exit code 1 (use -v to see invocation)
請確定libPaymentControl.a文件確實存在于此路徑,可能為上下文路徑配錯。
控件閃退異常'NSInvalidArgumentException', reason: '-[__NSCFConstantString newSizeWithFont:詳略]'
'NSInvalidArgumentException', reason: '-[__NSCFConstantString newSizeWithFont:以下略]: unrecognized selector sent to instance 0x[隨機數]'
出現以上問題是由于添加-ObjC宏的地方沒有配置正確,如果配-ObjC實在解決不了的話,可嘗試去掉-ObjC,改為-force_load+空格+控件路徑,如:-force_load $(PROJECT_DIR)/ libPaymentControl.a。
orientation異常
詳細現象為控件崩潰,報錯信息:Terminating app due to uncaught exception ‘UIApplicationInvalidInterfaceOrientation’, reason: ‘Supported orientations has no common orientation with the application, and shouldAutorotate is returning YES’ 請勿修改橫豎屏配置,iphone控件只能豎屏,ipad控件才支持橫豎屏。如果app本身為橫屏,請代碼控制橫豎屏,勿修改配置。
其他第三方靜態庫(如支付寶、微信等)的文件產生沖突duplicate symbols for architecture XXX
如:
請嘗試將添加-ObjC宏的地方修改為 -force_load+空格+控件路徑,如:-force_load $(PROJECT_DIR)/ libPaymentControl.a,這樣做不會影響支付寶等其他支付渠道功能。
控件界面無限加載
- 調用控件的邏輯應當在主線程中執行,子線程中盡量不要進行UI操作,無限加載等待實際是子線程死鎖所致。
- 請參考控件使用指南iOS “添加SDK包“里“添加-ObjC宏”,特別注意大小寫不要弄混。(此步驟操作有問題時也可修改為 -force_load+空格+控件路徑,如:-force_load $(PROJECT_DIR)/ libPaymentControl.a)。
- Build Setting -> Apple LLVM compiler Language-C++:
Attempt to present XX on XX while a presentation is in progress!
Warning: Attempt to present <UPNavController: 0x8bc24d0> on <tttViewController: 0x8b9a390> while a presentation is in progress!animation完成的時候再調用我們的插件,兩個present同時起會出警告。