iOS

此章节为您提供 iOS 端卡支付 SDK 的集成指南，帮助您快速开始手机 app 内的支付相关页面渲染。

集成准备

在您开始集成前，请阅读集成指南及 API 概述文档，了解服务端 API 的集成步骤及 API 的调用注意事项，并确保已完成以下预配置及环境准备工作：

在开发者中心获得 client ID
在开发者中心完成密钥配置
已安装 Xcode 12 或更高版本
确保 iOS 系统为 iOS 9 及以上版本

关键集成步骤

请根据以下步骤完成集成：

引入 SDK 包。

商户客户端

在开发者中心下载 SDK 包后，在项目中添加 AMSComponent.framework 框架，并确保在 Build Settings > Linking > Other Linker Flags 中添加 -ObjC 。

添加 AMSComponent.framework：

添加 -ObjC :

通过 AMSComponentCheckout创建 SDK 实例：

商户客户端

初始化收银台实例，包含以下参数：
- configuration：必传，AMSConfiguration 类型的一个对象，包含所有配置参数。
创建 AMSConfiguration 类，包含以下参数：
- locale: 选传，NSString 类型。商户客户端识别用户浏览器使用的语言种类，并传入浏览器多语言信息，SDK 根据此信息提供对应语言的页面。目前 SDK 仅支持以下四种多语言信息的值，如果传入的值不是以下四种，将提供英语页面：
  - en_US：英语
  - pt_BR：葡萄牙语
  - ko_KR：韩语
  - es_ES：西班牙语
- envType: 必传，NSString 类型。用于传入环境参数，支持的值包括：
  - kAMSCheckoutEnvSANDBOX：沙箱环境
  - kAMSCheckoutEnvPROD：生产环境
创建 AMSLoggerProtocol 接口的实例，用于管理日志输出，包含以下方法：
- logWithName(): 选传，默认输出日志的回调函数。

创建 SDK 实例的接口示例：

1@interface AMSConfiguration : NSObject
2/// Current language
3@property (nonatomic, copy) NSString *locale;
4
5@property (nonatomic, copy) AMSCheckoutEnv envType;
6
7@end
8
9@property (nonatomic, strong) AMSConfiguration *configuration;
10- (instancetype)init:(AMSConfiguration *)configuration;
11

创建收银台实例的配置项示例：

1AMSConfiguration *configuration = [AMSConfiguration new];
2configuration.locale = @"en_US";
3configuration.envType = kIAMSCheckoutEnvPROD;
4
5[[AMSComponentCheckout shared] setConfiguration:componentConfig];
6[AMSComponentCheckout shared].paymentDelegate = self;
7[AMSComponentCheckout shared].loggerDelegate = self;
8
9#pragma AMSPaymentProtocol
10- (void)onPaymentEventCallback:(NSString *)eventCode message:(NSString *)message
11{
12   NSLog(@"eventCode%@ message%@", eventCode, message);
13}
14
15#pragma AMSLogProtocol
16- (void)logWithName:(NSString *)name parameter:(nullable NSDictionary *)parameter
17{
18   NSLog(@"name%@ parameter%@", name, parameter);
19}
20

向 Alipay 服务器发起 支付会话创建 请求。

商户服务端

买家在支付方式选择页选择卡支付方式后，商户客户端自行实现支付按钮的点击事件监听。当监听到支付按钮被用户点击后，商户服务端需向 Alipay 服务器发起 支付会话创建 请求。收到支付会话创建请求的响应后，将响应中的 paymentSessionData 参数值用于步骤 4 。

注意：在调用 支付会话创建 接口时，请求参数 paymentRedirectUrl 的值需要使用您提供的支付完成后跳转页面对应的 URL Scheme 。

以下支付会话创建请求示例，仅包含了必传字段及部分选传字段：

1{
2  "order": {
3    "buyer": {
4      "buyerName": {
5        "firstName": "*****",
6        "fullName": "D***u",
7        "lastName": "Liu",
8        "middleName": "Skr"
9      },
10      "buyerRegistrationTime": "2022-01-01T09:30:00+08:00",
11      "referenceBuyerId": "tony.c"
12    },
13    "goods": [{
14      "goodsBrand": "AMSDM",
15      "goodsCategory": "card/ssr/adc",
16      "goodsName": "Goods No.1",
17      "goodsQuantity": "1",
18      "goodsSkuName": "SKU1",
19      "goodsUnitAmount": {
20        "currency": "USD",
21        "value": "10000"
22      },
23      "goodsUrl": "HangZhou LeiFenTa",
24      "referenceGoodsId": "amsdm_good_tony_c_20230227_095825_922"
25    }],
26    "orderAmount": {
27      "currency": "BRL",
28      "value": "2129"
29    },
30    "orderDescription": "AMSDM_GIFT",
31    "referenceOrderId": "amsdmorder_tony_c_20230227_095825_921"
32  },
33  "paymentAmount": {
34    "currency": "BRL",
35    "value": "2129"
36  },
37  "paymentFactor": {
38    "isAuthorization": true
39  },
40  "paymentMethod": {
41    "paymentMethodType": "CARD",
42    "paymentMethodMetaData":{
43        "paymentMethodRegion":"BR"
44    }
45  },
46  "paymentNotifyUrl": "https://www.google.com.sg",
47  "paymentRedirectUrl": "https://www.baidu.com",
48  "paymentRequestId": "amsdmpayk_tony_c_20230227_095825_920_532",
49  "productCode": "CASHIER_PAYMENT",
50  "settlementStrategy": {
51    "settlementCurrency": "USD"
52  },
53  "enableInstallmentCollection":"true"
54}

支付会话创建请求的响应示例：

1{
2  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
3  "paymentSessionExpiryTime": "2023-04-06T03:28:49Z",
4  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
5  "result": {
6    "resultCode": "SUCCESS",
7    "resultMessage": "success.",
8    "resultStatus": "S"
9  }
10}

使用实例对象中的 createComponent() 创建支付要素收集组件:

商户客户端

使用 paymentSessionData 参数创建配置对象: 将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 paymentSessionData 参数。
调用 createComponent() 函数创建支付要素收集组件。

创建支付要素组件的接口示例：

1- (void)createComponent:(NSString *)paymentType paymentSessionData:(NSString *)paymentSessionData;

调用 createComponent() 示例：

1[[AMSComponentCheckout shared] createComponent:@"CARD" paymentSessionData: paymentSessionData];

参考信息

事件码

SDK 提供的事件码如下：

SDK_INTERNAL_ERROR：加载浮层收银台失败。
SDK_CALL_URL_ERROR：此事件码代表以下事件信息中的一种情况：
- 跳转商户页面失败。
- 调用 支付会话创建 请求时 paymentRedirectUrl 参数未传入或未正确传入。

SDK_CREATECOMPONENT_ERROR：创建卡组件失败，需使用正确参数再次调用 createComponent()。

集成代码关键步骤示例

以下代码示例展示了集成过程中的关键步骤。代码中不包括调用 支付会话创建 接口的步骤示例，需要您自行处理服务端接口的调用。

1#import <AMSComponent/AMSComponent.h>
2
3
4步骤一：实例化sdk
5
6AMSConfiguration *configuration = [AMSConfiguration new];
7configuration.locale = @"en_US";
8
9[[AMSComponentCheckout shared] setConfiguration:componentConfig];
10[AMSComponentCheckout shared].paymentDelegate = self;
11[AMSComponentCheckout shared].loggerDelegate = self;
12
13#pragma AMSPaymentProtocol
14- (void)onPaymentEventCallback:(NSString *)eventCode message:(NSString *)message
15{
16NSLog(@"eventCode%@ message%@", eventCode, message);
17}
18
19#pragma AMSLogProtocol
20- (void)logWithName:(NSString *)name parameter:(nullable NSDictionary *)parameter
21{
22NSLog(@"name%@ parameter%@", name, parameter);
23}
24
25// 步骤二：服务端创建调用支付会话接口，获取paymentSessionData
26
27
28// 步骤三：创建渲染卡组件
29[[AMSComponentCheckout shared] createComponent:@"CARD" paymentSessionData: paymentSessionData];