iOS

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

集成准备

在开始集成前，您需要：

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

集成步骤

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

集成 SDK 资源包

商户客户端

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

获取 Apple 商家标识符

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

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

创建新的 Apple Pay 证书

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

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

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

注意：

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

iOS

集成 XCode

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

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

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

Editor

通过 AMSCashierPayment 创建 SDK 实例

商户客户端

初始化收银台实例，包含以下参数：
- configuration：必传，AMSCashierPaymentConfiguration 类型的一个对象，包含所有配置参数。
创建 AMSCashierPaymentConfiguration 类，包含以下参数：
- options：选传，NSDictionary 类型，用于设置是否使用沙箱环境，支持的值包括：
  - "sandbox", "true"：沙箱环境
  - "sandbox", "false"：生产环境
实现 AMSPaymentProtocol 的协议，用于后续流程中对应事件发生时的处理，包含以下方法：
- onEventCallback：收银台支付事件回调函数，返回事件码（eventCode）和事件具体信息（eventResult）。

创建 SDK 实例的接口示例：

Objective-C

Editor

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

商户服务端

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

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

发起支付会话创建请求

请求示例

响应示例

Editor

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

商户客户端

使用 sessionData 参数创建配置对象：将 支付会话创建 请求的响应中获取的 paymentSessionData 字段的完整数据传入 sessionData 参数。
调用 createComponent() 函数创建支付要素收集组件。
调用实例对象中的 onDestroy() 函数进行 SDK 组件的资源回收，请在以下两种场景中调用：
- 用户退出支付页面时，需要回收 支付会话创建 中的组件资源。
- 用户发起多笔支付时，需要回收上一次 支付会话创建 中的组件资源。

调用 createComponent() 示例：

Objective-C

Editor

事件码

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

SDK_PAYMENT_SUCCESSFUL：支付已受理。您可以调用 支付结果查询 接口查询支付结果。
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.	支付被拒绝，支付要素填写错误。