Antom, leading provider of tailored payment solutions
Contact Us
登 录

iOS

此章节为您提供 Apple Pay 支付方式的 SDK 集成指南，帮助您快速开始 iOS Apple Pay 相关页面的渲染。

 

集成准备

在开始集成前，您需要：

  • 在 Antom Dashboard 平台获得 client ID 并完成密钥配置
  • 安装 Xcode 12 或更高版本。
  • 确保 iOS 系统为 iOS 11 及以上版本。

 

集成步骤

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

1

集成 SDK 资源包

商户客户端

请查阅 iOS 端集成 SDK 资源包文档。

 

 

2

获取 Apple 商家标识符

  1. 登录 Apple 开发者中心网站，通过注册新的标识符来获取 Apple 商家标识符。
  2. 在表单中填写描述和标识符，确保准确描述您的应用，标识符建议使用您的应用名，例如：merchant.com.{{YOUR_APP_NAME}}。

更多注册细节请参考 Apple Pay 官方集成文档。

 

3

创建新的 Apple Pay 证书

Apple Pay 证书可以为您的应用加密支付数据。请按照以下步骤为您的应用创建证书：

  1. 联系 Antom 技术支持获取证书签名请求 (CSR) 文件，以获取 Apple 安全证书。
  2. 打开 Apple 开发者中心的 Merchant IDs 管理页面（Certificates, Identifiers & Profiles 页面），点击 Identifiers，选择要添加证书的 Merchant ID 和商家标识符。
  3. 在 Apple Pay Payment Processing Certificate 选项下点击 Create Certificate。
  4. 在 Create a New Certificate 页面点击 Choose File，选择并上传您从 Antom 获得的 CSR 文件。上传成功后 Apple Pay 会为您提供一个可下载的证书文件。
  5. 将证书文件下载到您的本地，并将该文件发送给 Antom 以验证您证书详情的正确性。

更多操作细节请参考 Apple Pay 官方集成文档。

注意：

  • CSR 文件与证书一一对应，如果您切换了 Apple 商家 ID，须重新获取 CSR 文件并创建新的 Apple 安全证书。
  • 首次点击 Create Certificate 时会出现以下提示，选择 No 并继续。

4

集成 XCode

打开 Xcode，在项目设置中点击签名和功能选项卡，添加 Apple Pay 功能到您的应用程序中。如果系统提示您登录开发者账户，选择您在步骤 3.2 中创建证书的商家 ID 即可。

 

 

5

检查用户设备是否支持 Apple Pay

请使用右侧代码检查您用户的设备是否支持 Apple Pay。如果支持您可在您的应用程序中显示 Apple Pay 这一支付选项。

 

 

1NSDictionary *params = @{
2    // 支付方式 必传
3    @"paymentMethodType" : @"CARD_APPLE_PAY",
4    // 是否为recurringPayment，默认为NO 可选
5    @"applePayRecurringPayment" : @(YES)
6};
7[AMSCashierPayment.shared canMakePaymentsWithParams:params complete:^(BOOL available) {
8    //是否显示ApplePay按钮
9}];
6

通过 AMSCashierPayment 创建 SDK 实例

商户客户端
  1. 初始化收银台实例，包含以下参数：
    • configuration：必传，AMSCashierPaymentConfiguration 类型的一个对象，包含所有配置参数。
  2. 创建 AMSCashierPaymentConfiguration 类，包含以下参数：
    • options：选传，NSDictionary 类型，用于设置是否使用沙箱环境，支持的值包括：​
      • "sandbox", "true"：沙箱环境
      • "sandbox", "false"：生产环境
  3. 实现 AMSPaymentProtocol 的协议，用于后续流程中对应事件发生时的处理，包含以下方法：
    • ​onEventCallback：收银台支付事件回调函数，返回事件码（eventCode）和事件具体信息（eventResult）。
创建 SDK 实例的接口示例：
1#import <AMSComponent/AMSComponent-Swift.h>
2
3AMSCashierPaymentConfiguration *componentConfig = [AMSCashierPaymentConfiguration new];
4// sandbox变更设置沙箱环境，不设置为线上正式环境
5NSDictionary *options = @{@"sandbox": @"true"};
6componentConfig.options = options;
7
8[[AMSCashierPayment shared] initConfiguration:componentConfig];
9
10[AMSCashierPayment shared].paymentDelegate = self;
11[[AMSCashierPayment shared] createComponent:paymentSessionData];
12
13#pragma AMSPaymentProtocol
14- (void)onEventCallback:(NSString *)eventCode eventResult:(AMSEventResult *)eventResult
15{
16   NSLog(@"eventCode%@ eventResult%@", eventCode, eventResult);
17}
7

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

商户服务端

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

注意：在调用 createVaultingSession 接口时，请求参数 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": "testBuyer"
12    },
13    "env": {
14      "browserInfo": {
15        "acceptHeader": "AcceptHeaded111",
16        "javaEnabled": true,
17        "javaScriptEnabled": false,
18        "language": "EN",
19        "userAgent": "agentagentagentagentagent"
20      },
21      "clientIp": "1.*.*.*",
22      "osType": "IOS",
23      "terminalType": "WEB"
24    },
25    "extendInfo": "{}",
26    "goods": [{
27      "goodsBrand": "AMSDM",
28      "goodsCategory": "card/ssr/adc",
29      "goodsName": "Goods No.1",
30      "goodsQuantity": "1",
31      "goodsSkuName": "SKU1",
32      "goodsUnitAmount": {
33        "currency": "USD",
34        "value": "10000"
35      },
36      "goodsUrl": "HangZhou LeiFenTa",
37      "referenceGoodsId": "amsdm_good_test_buyer_20240313_004333_820"
38    }],
39    "orderAmount": {
40      "currency": "KRW",
41      "value": "3000"
42    },
43    "orderDescription": "AMSDM_GIFT",
44    "referenceOrderId": "amsdmorder_test_buyer_20240313_004333_820"
45  },
46  "paymentAmount": {
47    "currency": "KRW",
48    "value": "3000"
49  },
50  "paymentFactor": {
51    "isAuthorization": false
52  },
53  "paymentMethod": {
54    "paymentMethodType": "CARD_APPLE_PAY"
55  },
56  "paymentNotifyUrl": "https://www.google.com.sg",
57  "paymentRedirectUrl": "https://www.baidu.com",
58  "paymentRequestId": "amsdmpay_test_buyer_123456789",
59  "productCode": "CASHIER_PAYMENT",
60  "userDefinedInfo": "{}"
61}
8

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

商户客户端
  1. 使用 sessionData 参数创建配置对象：将 createVaultingSession 请求的响应中获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。
  2. 调用 createComponent() 函数创建支付要素收集组件。

  3. 调用实例对象中的 onDestroy() 函数进行 SDK 组件的资源回收，请在以下两种场景中调用：

调用 createComponent() 示例：
1[[AMSCashierPayment shared] createComponent:sessionData];
2//销毁组件
3[[AMSCashierPayment shared] onDestroy];
事件码

SDK 提供的支付事件码有以下几种：

  • SDK_PAYMENT_SUCCESSFUL：支付已受理。您可以调用 inquiryPayment​ 接口查询支付结果。
  • SDK_PAYMENT_FAIL：支付失败。请您根据下方 errorCode 提示信息重新引导用户支付。
  • SDK_PAYMENT_ERROR：支付状态异常。请您根据 message 中的数据信息排查可能出现的问题。
  • SDK_PAYMENT_CANCEL：支付取消。买家未点击支付并关闭支付窗口。可以用在有效期内的 paymentSessionData 重新调用SDK。如已过期，需要重新请求 paymentSessionData。

 

服务端结果码（result.errorCode）：

错误码

值

消息

建议

SUCCESS

S

Success

无需进一步操作。

ORDER_NOT_EXIST

F

The order does not exist.

建议重新下单。

PAYMENT_IN_PROCESS

U

The payment is being processed.

等待支付通知或主动查询结果。

PROCESS_FAIL

F

A general business failure occurred.

通常需要人工确认该问题。 建议您联系 Antom 技术支持解决该问题。

UNKNOWN_EXCEPTION

U

An API call has failed, which is caused by unknown reasons.

等待支付通知或主动查询结果。

INQUIRY_PAYMENT_SESSION_FAILED

F

Failed to retrieve paymentSessionData, which may have expired or is in an unknown state.

 

会话已过期。等待支付通知或主动查询结果。

PAGE_ELEMENT_ILLEGAL

U

The payment information is incorrect.

支付被拒绝，支付要素填写错误。