银联手机支付控件官方使用指南(ios版)
目录
版本信息... 2
目录 3
1 概述... 1
2 支付流程介绍... 1
3 测试帐号... 2
4 iOS客户端... 3
4.1 SDK说明... 3
4.2 接口说明... 4
4.3 添加SDK包... 5
4.4 调用插件... 5
5 常见问题总结... 6
5.1 iOS平台常见问题... 6
1 概述
银联手机支付控件(以下简称支付控件)，主要为合作商户的手机客户端或手机Web网站提供安全、便捷的支付服务。目前支付控件支持Android和iOS两个平台，用户通过在支付控件中输入银行卡卡号、手机号、密码（借记卡和预付卡）或者CVN2、有效期（信用卡）、验证码等要素完成支付。
2 支付流程介绍
通过支付控件进行交易的流程如下图：
流程图说明：
（1）用户在客户端中点击购买商品，客户端发起订单生成请求到商户后台；
（2）商户后台收到订单生成请求后，按照《手机控件支付产品接口规范》组织并推送订单信息至银联后台；
（3）银联后台接收订单信息并检查通过后，生成对应交易流水号（即TN），并回复交易流水号至商户后台（应答要素：交易流水号等）；
（4）商户后台接收到交易流水号，将交易流水号返回给客户端；
（5）客户端通过交易流水号（TN）调用支付控件；
（6）用户在支付控件中输入相关支付信息后，由支付控件向银联后台发起支付请求；
（7）支付成功后，银联后台将支付结果通知给商户后台；
（8）银联将支付结果通知支付控件；
（9）支付控件显示支付结果并将支付结果返回给客户端；
注: 本文档主要关注上述流程中（5）、（9）部分的实现
目前各个平台支持的设备情况如下：
Android平台SDK主要适用于Android 2.1及以上版本的终端设备；
iOS版本支付控件适用iOS 6.0及以上版本终端设备。
3 测试帐号
提供测试使用卡号、手机号信息（此类信息仅供测试，不会发生正式交易）
|
招商银行借记卡：6226090000000048 |
|
华夏银行贷记卡：6226388000000095 |
4 iOS客户端
本小节提供给那些具有一定iOS编程经验和了解面向对象概念的读者使用。
SDK文件所在目录：upmp_iphone/sdk，以下部分所说文件，均在该目录中查找。
4.1 SDK说明
SDK分为以下两个版本：
① 支持纯无卡交易静态库，以下简称UPPayPlugin，包含文件：
UPPayPlugin.h
UPPayPluginDelegate.h
libUPPayPlugin.a
② 支持纯无卡交易和VIPOS音频口支付静态库,以下简称UPPayPluginPro，包含文件：
UPPayPluginPro.h
UPPayPluginDelegate.h
libUPPayPluginPro.a
4.2 接口说明
|
+ (BOOL)startPay:(NSString*)tn mode:(NSString*)mode viewController:(UIViewController*)viewController delegate:(id<UPPayPluginDelegate>)delegate; |
各个参数的介绍如表3-1：
表3-1 接口参数说明
|
参数名称 |
类型 |
含义 |
|
tn |
NSString* |
必填项； 交易流水号信息，银联后台生成，通过商户后台返回到客户端并传入支付控件； |
|
mode |
NSString* |
必填项； 接入模式设定，两个值： @"00":代表接入生产环境（正式版本需要）； @"01"：代表接入开发测试环境（测试版本需要）； |
|
viewController |
UIViewController* |
必填项； 商户应用程序调用银联手机支付的当前UIViewController； |
|
delegate |
id<UPPayPluginDelegate> |
必填项； 实现UPPayPluginDelegate方法的UIViewController； |
4.3 添加SDK包
a) 根据商户选择的SDK版本，将sdk/inc目录和sdk/libs目录下对应版本的三个文件添加到UPPayDemo工程中；
b) 如果你选择的是UPPayPlugin版本，添加QuartzCore.framework、Security.framework到工程中；
c) 如果你选择的是UPPayPluginPro版本，添加QuartzCore.framework、AudioToolbox.framework, CoreAudio.framework、 MediaPlayer.framework, AVFoundation.framework和Security.framework到工程中；
d) 在工程的Build Settings中找到Other Linker Flags中添加-ObjC宏；
4.4 调用插件
a) 在需要调用支付控件的源文件内引用头文件UPPayPlugin.h或UPPayPluginPro.h（注意：如果工程的compile source as 选项的值不是Objective–C++，则引用此头文件的文件类型都要改为.mm）
b) 通过调用
+ (BOOL)startPay:(NSString*)tn
mode:(NSString*)mode
viewController:(UIViewController*)viewController
delegate:(id<UPPayPluginDelegate>)delegate;
实现控件的调用
c) 处理支付结果
银联手机支付控件有三个支付状态返回值：success、fail、cancel，分别代表：支付成功、支付失败、用户取消支付。这三个返回状态值以字符串的形式作为回调函数参数(NSString*)result返回。通过在工程中添加头文件“UPPayPluginDelegate.h”，在处理交易结果的界面，实现UPPayPluginDelegate接口，根据该头文件中的回调函数：-(void)UPPayPluginResult:(NSString*)result来实现回调方法，从而可以根据支付结果的不同进行相关的处理。
5 常见问题总结
更多请参见https://open.unionpay.com帮助中心-FAQ
5.1 iOS平台常见问题
5.1.1 怎么加-ObjC宏
选择工程targets——》build settings ->Linking->other linker flags
5.1.2 编译时提示Undefined for architecture XXX 错误?
如：
1）由于支付控件使用到了C、C++和OC混编的情况，所以商户工程引入UPPayPlugin.h头文件以后可能会出现链接错误。这个时候可以通过两种方式解决：
① 将涉及到引用UPPayPlugin.h的源文件的后缀名都改为.mm；
② 如果商户不想修改源文件的后缀名，可以在工程中添加一个空的继承自NSObject的类，并将文件.m后缀名该改为.mm即可。方法为new file->Objective-C class->类名自取->保存->修改后缀名为.mm。
③ 将工程的compile source as 选项的值不是Objective–C++；
2）由于在UPPayDemo工程中添加了自定义的库文件libUPPayPlugin.a，当编译Demo工程时，应该检查工程设置Search Paths里的Framework Search Paths、Header Search Paths、Library Search Paths的路径设置，看设置路径是否正确，另外还要注意里边是否多余一些不确定的路径
3) 将xcode工程中Build Setting -> Apple LLVM compiler Language 标签下的C++ Language Dialect 和 C++ Standard Library 属性值修改为 Compiler Default。
如实在无法解决，尝试添加-ObjC宏的地方修改为 -force_load+空格+控件路径，如：-force_load $(PROJECT_DIR)/libUPPayPlugin.a
如果还报错，上下文应该会有libUPPayPlugin.a文件找不到异常，比如
ld: file not found: /Users/apple/Desktop/Communication 2/libUPPayPlugin.a
clang: error: linker command failed with exit code 1 (use -v to see invocation)
请确定libUPPayPlugin.a文件确实存在于此路径，可能为上下文路径配错。
5.1.3 控件闪退异常'NSInvalidArgumentException', reason: '-[__NSCFConstantString newSizeWithFont:以下略]
'NSInvalidArgumentException', reason: '-[__NSCFConstantString newSizeWithFont:以下略]:
unrecognized selector sent to instance 0x[随机数]'
如图：
添加-ObjC宏的地方没有配置正确，如果配-ObjC实在解决不了的话，可尝试去掉-ObjC，改为-force_load+空格+控件路径，如：-force_load $(PROJECT_DIR)/libUPPayPlugin.a
5.1.4 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本身为横屏，请代码控制横竖屏，勿修改配置。
5.1.5 其他第三方静态库（如支付宝、微信等）的文件产生冲突duplicate symbols for architecture XXX
如：
控件指南中提到的添加-ObjC宏的地方修改为 -force_load+空格+控件路径，如：-force_load $(PROJECT_DIR)/libUPPayPlugin.a。
不会影响支付宝的。
5.1.6 在刚进控件的界面无限加载
1. 调用控件的逻辑放在主线程中执行。因为在子线程中不允许操作UI，无限菊花实是子线程死锁了。
2. 请看下控件使用指南iOS “添加SDK包“里“添加-ObjC宏”，也注意大小写别写错了。（此步骤操作有问题时也可修改为
-force_load+空格+控件路径，如：-force_load
$(PROJECT_DIR)/libUPPayPlugin.a）
3. Build
Setting -> Apple LLVM compiler Language-C++：
5.1.7 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同时起会出警告。
