iOS
此章节为您提供 iOS 端卡支付 SDK 的集成指南,帮助您快速开始手机 app 内的支付相关页面渲染。
集成准备
关键集成步骤
请根据以下步骤完成集成:
1
引入 SDK 包。
商户客户端
在开发者中心下载 SDK 包后,在项目中添加 AMSComponent.framework 框架,并确保在 Build Settings > Linking > Other Linker Flags 中添加 -ObjC 。
添加 AMSComponent.framework:
Loading image
添加 -ObjC :
Loading image
2
通过 AMSComponentCheckout创建 SDK 实例:
商户客户端
- 初始化收银台实例,包含以下参数:
- configuration:必传,AMSConfiguration 类型的一个对象,包含所有配置参数。
- 创建
AMSConfiguration类,包含以下参数:- locale: 选传,NSString 类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器多语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 仅支持以下四种多语言信息的值,如果传入的值不是以下四种,将提供英语页面:
en_US:英语pt_BR:葡萄牙语ko_KR:韩语es_ES:西班牙语
- envType: 必传,NSString 类型。用于传入环境参数,支持的值包括:
kAMSCheckoutEnvSANDBOX:沙箱环境kAMSCheckoutEnvPROD:生产环境
- locale: 选传,NSString 类型。商户客户端识别用户浏览器使用的语言种类,并传入浏览器多语言信息,SDK 根据此信息提供对应语言的页面。目前 SDK 仅支持以下四种多语言信息的值,如果传入的值不是以下四种,将提供英语页面:
- 创建
AMSLoggerProtocol接口的实例,用于管理日志输出,包含以下方法:-
logWithName(): 选传,默认输出日志的回调函数。
-
创建 SDK 实例的接口示例:
@interface AMSConfiguration : NSObject
/// Current language
@property (nonatomic, copy) NSString *locale;
@property (nonatomic, copy) AMSCheckoutEnv envType;
@end
@property (nonatomic, strong) AMSConfiguration *configuration;
- (instancetype)init:(AMSConfiguration *)configuration;
创建收银台实例的配置项示例:
AMSConfiguration *configuration = [AMSConfiguration new];
configuration.locale = @"en_US";
configuration.envType = kIAMSCheckoutEnvPROD;
[[AMSComponentCheckout shared] setConfiguration:componentConfig];
[AMSComponentCheckout shared].paymentDelegate = self;
[AMSComponentCheckout shared].loggerDelegate = self;
#pragma AMSPaymentProtocol
- (void)onPaymentEventCallback:(NSString *)eventCode message:(NSString *)message
{
NSLog(@"eventCode%@ message%@", eventCode, message);
}
#pragma AMSLogProtocol
- (void)logWithName:(NSString *)name parameter:(nullable NSDictionary *)parameter
{
NSLog(@"name%@ parameter%@", name, parameter);
}
买家在支付方式选择页选择卡支付方式后,商户客户端自行实现支付按钮的点击事件监听。当监听到支付按钮被用户点击后,商户服务端需向 Alipay 服务器发起 支付会话创建 请求。收到支付会话创建请求的响应后,将响应中的 paymentSessionData 参数值用于步骤 4 。
注意:在调用 支付会话创建 接口时,请求参数 paymentRedirectUrl 的值需要使用您提供的支付完成后跳转页面对应的 URL Scheme 。
以下支付会话创建请求示例,仅包含了必传字段及部分选传字段:
{
"order": {
"buyer": {
"buyerName": {
"firstName": "*****",
"fullName": "D***u",
"lastName": "Liu",
"middleName": "Skr"
},
"buyerRegistrationTime": "2022-01-01T09:30:00+08:00",
"referenceBuyerId": "tony.c"
},
"goods": [{
"goodsBrand": "AMSDM",
"goodsCategory": "card/ssr/adc",
"goodsName": "Goods No.1",
"goodsQuantity": "1",
"goodsSkuName": "SKU1",
"goodsUnitAmount": {
"currency": "USD",
"value": "10000"
},
"goodsUrl": "HangZhou LeiFenTa",
"referenceGoodsId": "amsdm_good_tony_c_20230227_095825_922"
}],
"orderAmount": {
"currency": "BRL",
"value": "2129"
},
"orderDescription": "AMSDM_GIFT",
"referenceOrderId": "amsdmorder_tony_c_20230227_095825_921"
},
"paymentAmount": {
"currency": "BRL",
"value": "2129"
},
"paymentFactor": {
"isAuthorization": true
},
"paymentMethod": {
"paymentMethodType": "CARD",
"paymentMethodMetaData":{
"paymentMethodRegion":"BR"
}
},
"paymentNotifyUrl": "https://www.google.com.sg",
"paymentRedirectUrl": "https://www.baidu.com",
"paymentRequestId": "amsdmpayk_tony_c_20230227_095825_920_532",
"productCode": "CASHIER_PAYMENT",
"settlementStrategy": {
"settlementCurrency": "USD"
},
"enableInstallmentCollection":"true"
}支付会话创建请求的响应示例:
{
"paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
"paymentSessionExpiryTime": "2023-04-06T03:28:49Z",
"paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}4
使用实例对象中的 createComponent() 创建支付要素收集组件:
商户客户端
- 使用 paymentSessionData 参数创建配置对象: 将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 paymentSessionData 参数。
- 调用
createComponent()函数创建支付要素收集组件。
创建支付要素组件的接口示例:
- (void)createComponent:(NSString *)paymentType paymentSessionData:(NSString *)paymentSessionData;调用 createComponent() 示例:
[[AMSComponentCheckout shared] createComponent:@"CARD" paymentSessionData: paymentSessionData];参考信息
事件码
SDK 提供的事件码如下:
-
SDK_INTERNAL_ERROR:加载浮层收银台失败。 -
SDK_CALL_URL_ERROR:此事件码代表以下事件信息中的一种情况:-
跳转商户页面失败。
-
调用 支付会话创建 请求时 paymentRedirectUrl 参数未传入或未正确传入。
-
-
SDK_CREATECOMPONENT_ERROR:创建卡组件失败,需使用正确参数再次调用createComponent()。
集成代码关键步骤示例
以下代码示例展示了集成过程中的关键步骤。代码中不包括调用 支付会话创建 接口的步骤示例,需要您自行处理服务端接口的调用。
#import <AMSComponent/AMSComponent.h>
步骤一:实例化sdk
AMSConfiguration *configuration = [AMSConfiguration new];
configuration.locale = @"en_US";
[[AMSComponentCheckout shared] setConfiguration:componentConfig];
[AMSComponentCheckout shared].paymentDelegate = self;
[AMSComponentCheckout shared].loggerDelegate = self;
#pragma AMSPaymentProtocol
- (void)onPaymentEventCallback:(NSString *)eventCode message:(NSString *)message
{
NSLog(@"eventCode%@ message%@", eventCode, message);
}
#pragma AMSLogProtocol
- (void)logWithName:(NSString *)name parameter:(nullable NSDictionary *)parameter
{
NSLog(@"name%@ parameter%@", name, parameter);
}
// 步骤二:服务端创建调用支付会话接口,获取paymentSessionData
// 步骤三:创建渲染卡组件
[[AMSComponentCheckout shared] createComponent:@"CARD" paymentSessionData: paymentSessionData];