Airwallex iOS SDK

概述

Airwallex iOS SDK 可以满足您在应用中集成简单、快速和安全的支付功能的需求。它提供了简单易用的 API 将敏感的信用卡数据直接发送到 Airwallex，同时还提供了一个强大且可定制的界面，用于收集用户的支付详情。

我们支持以下本地化语言：英语、简体中文、繁体中文、法语、德语、日语、韩语、葡萄牙语（葡萄牙）、葡萄牙语（巴西）、俄语、西班牙语、泰语。

开始集成
要求
示例项目
集成步骤
贡献

=================

开始集成

请按照我们的集成指南并探索示例项目，以快速使用 Airwallex iOS SDK 设置支付功能。

Tip

从旧版 SDK 升级的相关改动可以参考我们的迁移文档

要求

iOS 13.0+
Xcode 15.4+（对于旧版本的 Xcode，请参考 5.4.3 版本）

示例项目

示例代码(Examples)可以在最新的 Xcode 上运行。请按照以下步骤操作。

克隆源代码

git clone git@github.com:airwallex/airwallex-payment-ios.git

安装依赖并打开项目

确保已安装 Cocoapods，然后在项目目录中运行以下命令：

pod install

Tip

更新初始化设置文件（可选）

更新 Examples/Keys 文件夹中的 Keys.json。
构建并运行 Examples

Keys.json用于提供 Examples 项目的一些默认设置，您可以随时使用应用内的设置页面更改这些设置

集成步骤

安装

Swift Package Manager

Airwallex iOS SDK 支持通过 Swift Package Manager 集成。要将其集成到您的项目中，请按照以下步骤操作：

按照 Apple 的指南添加包依赖。
使用以下 URL 获取 Airwallex 包 https://github.com/airwallex/airwallex-payment-ios
使用 6.1.1 或更高版本。

您可以通过添加 Airwallex 集成除微信支付外的所有组件。您也可以根据您的支付需求选择性的添加组件：

AirwallexPaymentSheet: 提供 UI 集成
AirwallexPayment: 提供 low-level API 集成
AirwallexWeChatPay: 集成微信支付，如果您需要支持微信支付请务必添加此依赖

Size Impact

集成方式	包含的组件	IPA 包增加的大小
Low-Level API 集成	AirwallexCore AirwallexPayment	1.20 MB
UI 集成	AirwallexCore AirwallexPayment AirwallexPaymentSheet	2.74 MB
全部组件	AirwallexCore AirwallexPayment AirwallexPaymentSheet AirwallexWeChatPay	3.53 MB

The IPA size increases shown above reflect the additional archive size when integrating the Airwallex SDK using Swift Package Manager (SPM) into an otherwise empty project, measured for each integration style. 上述 IPA 体积的增长是在一个空项目中，通过 Swift Package Manager (SPM) 使用不同方式集成 Airwallex SDK 后，归档 IPA 文件增加的大小。

CocoaPods

Airwallex iOS SDK 支持通过 CocoaPods集成。

您可以通过添加 Airwallex 集成除微信支付外的所有组件。您也可以根据您的支付需求选择性的添加组件：

pod 'Airwallex', '~> 6.1.1'

您也可以直接指定 subspec 来避免引入不需要的依赖：

pod 'Airwallex/AirwallexPaymentSheet' # 提供 UI 集成 
pod 'Airwallex/AirwallexPayment' # 提供 low-level API 集成
pod 'Airwallex/AirwallexWeChatPay' # 集成微信支付，如果您需要支持微信支付请务必添加此依赖

运行以下命令：

pod install

必要设置

当您的应用启动时，使用 mode 配置 SDK。

Airwallex.setMode(.demoMode) // .demoMode, .stagingMode, .productionMode

Customer ID

Important

订阅支付：必须绑定 customer ID
带intent订阅支付：必须绑定 customer ID
一次性支付：
- 保存银行卡：必须绑定 customer ID
- 不保存银行卡：可选

请在您的服务器端为您的用户生成或检索 customer ID。相关接口信息，请参阅Airwallex API 文档

创建 `AWXSession`

如果您想进行一次性支付，请创建 AWXOneOffSession。

let session = AWXOneOffSession()
session.countryCode = "Your country code"
session.billing = "Your shipping address"
session.returnURL = "App return url"

如果您想进行订阅支付，请创建 AWXRecurringSession。

let session = AWXRecurringSession()
session.countryCode = "Your country code"
session.billing = "Your shipping address"
session.returnURL = "App return url"
session.setCurrency("Currency code")
session.setAmount("Total amount")
session.setCustomerId("Customer ID")
session.nextTriggerByType = "customer or merchant";
session.merchantTriggerReason = "Unscheduled or scheduled";

如果你想完成带 payment intent 的订阅支付，请创建 AWXRecurringWithIntentSession。

let session = AWXRecurringWithIntentSession()
session.countryCode = "Your country code"
session.billing = "Your shipping address"
session.returnURL = "App return url"
session.nextTriggerByType = "customer or merchant"
session.merchantTriggerReason = "Unscheduled or scheduled"

Tip

您只需为订阅支付（AWXRecurringSession）显式设置客户 ID。对于一次性支付和带 intent 的订阅支付，会自动从 session.paymentIntent 中获取 customer ID。

创建 `AWXPaymentIntent`

Important

一次性支付: 必须创建 AWXPaymentIntent 带 intent 订阅支付: 必须创建 AWXPaymentIntent 订阅支付 不需要创建 AWXPaymentIntent。

在您的服务器端创建payment intent，然后将payment intent返回到移动端。

相关接口信息，请参阅 Airwallex API 文档

let paymentIntent = "The payment intent created on your server"
// 将 payment intent 和 session 绑定
session.paymentIntent = paymentIntent

设置客户端密钥

对于一次性支付和带 intent 的订阅支付，使用 paymentIntent 中的 clientSecret

AWXAPIClientConfiguration.shared().clientSecret = paymentIntent.clientSecret

对于订阅支付，您需要使用 customer ID 在服务器端创建 客户端密钥并将其传递给 AWXAPIClientConfiguration。

相关接口信息，请参阅 Airwallex API 文档

let clientSecret = "The client secret generated with customer ID on your server"
AWXAPIClientConfiguration.shared().clientSecret = clientSecret

可选设置

微信支付

确保添加 AirwallexWeChatPay（Swift package manager）或 Airwallex/AirwallexWechatPay（Cocoapods）的依赖
按照微信官方集成文档设置 WechatOpenSDK

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        WXApi.registerApp("WeChat app ID", universalLink: "universal link of your app")
        return true
    }
    
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
        return WXApi.handleOpen(url, delegate: self)
    }
}

extension AppDelegate: WXApiDelegate {
    func onResp(_ resp: BaseResp) {
        if let response = resp as? PayResp {
            switch response.errCode {
                // handle payment result
            }
        }
    }
}

完成支付后，微信将跳转回商户应用并回调到 onResp()函数。微信 SDK 会在商户的服务端获取到获取到支付状态后更新对应 payment intent 的状态，所以请持续监听 onResp() 的回调

Note

我们使用基于 WechatOpenSDK 2.0.4 版本重新构建的动态框架 WechatOpenSDKDynamic.xcframework 进行微信支付集成。通过使用重新构建的动态框架我们达到以下两个目的：

从 SPM Target AirwallexWeChatPay 中移除不安全的 linker flag -ObjC、-all_load
去除现代应用程序不再需要的 armv7 和 i386 架构。

Apple Pay

Airwallex iOS SDK 支持 Apple Pay 支付方式。

请确保您的应用已正确设置 Apple Pay。
- 具体步骤请参阅 Apple 的官方文档。
确保您的 Airwallex 账户中已启用 Apple Pay。
使用您的商户标识符创建 AWXApplePayOptions 并更新到 session.applePayOptions 上

您可以自定义 Apple Pay 选项以对支付方式做出限制或提供额外的交易信息。全部可配置项信息请参阅 AWXApplePayOptions.h 头文件。

let options = AWXApplePayOptions(merchantIdentifier: applePayMerchantId)
options.additionalPaymentSummaryItems = [
    .init(label: "goods", amount: 10),
    .init(label: "tax", amount: 1)
]
options.merchantCapabilities = [.threeDSecure, .debit]
options.requiredBillingContactFields = [.postalAddress]
options.supportedCountries = ["AU"]
options.totalPriceLabel = "COMPANY, INC."

let session = AWXOneOffSession()
//  configure other properties
...
session.applePayOptions = AWXApplePayOptions(merchantIdentifier: "Your Merchant Identifier")// required for Apple Pay

Important

请注意，我们目前仅支持以下支付网络：

Visa
MasterCard
ChinaUnionPay
Maestro
Amex
Discover
JCB

且当前版本不支持 Coupon

UI 集成

启动完整支付列表（推荐）

Note

通过UI集成您可以在您的app中使用我们预构建的 UI 收集支付详情、账单详情并确认支付。

请确保您已经添加对 Airwallex 或 AirwallexPaymentSheet 的依赖。在结账时使用 AWXUIContext 启动支付流程，用户能够通过支付列表选择您支持的支付方式。

AWXUIContext.launchPayment(
    from: "hosting view controller which also handles AWXPaymentResultDelegate",
    session: "The session created above",
    filterBy: "An optional array of payment method names used to filter the payment methods returned by the server",
    launchStyle: ".push/.present",
    layout: ".tab/.accordion"
)

我们提供了 tab 和 accordian 两种风格的支付列表:

仅展示卡支付

AWXUIContext.launchCardPayment(
    from: "hosting view controller which also handles AWXPaymentResultDelegate",
    session: "The session created above",
    supportedBrands: "accepted card brands, should not be empty"
)

Tip

如果您想仅展示卡支付并希望能够使用已保存的卡支付，可以启动完整支付列表并通过 filterBy 参数限制仅展示卡支付

AWXUIContext.launchPayment(
    from: "hosting view controller which also handles AWXPaymentResultDelegate",
    session: "The session created above",
    filterBy: [AWXCardKey]
)

按名称启动支付方式

AWXUIContext.launchPayment(
    name: "payment method name",
    from: "hosting view controller",
    session: "The session created above",
    paymentResultDelegate: "object handles AWXPaymentResultDelegate"
)

Tip

可用的支付方式名称可以通过Airwallex API获取

自定义主题色

您可以自定义 Airwallex UI 的主题色。

AWXTheme.shared().tintColor = .red

Low-level API 集成

您也可以基于 Low-level API 构建您自己的UI并向客户提供支付功能。

Note

请确保您已添加对 Airwallex 或 AirwallexPayment 的依赖。
您仍然需要完成必要设置中列出的所有步骤。

您可以通过Airwallex API 文档来获取自定义UI需要的各种信息

创建 PaymentSessionHandler

let paymentSessionHandler = PaymentSessionHandler(
    session: "The session created above", 
    viewController: "hosting view controller which also handles AWXPaymentResultDelegate"
)
self.paymentSessionHandler = paymentSessionHandler

Tip

初始化后，您需要将 paymentSessionHandler 存储在与视图生命周期绑定的视图控制器或类中

使用卡支付

// Confirm intent with card and billing
paymentSessionHandler.startCardPayment(
    with: "The AWXCard object collected by your custom UI",
    billing: "The AWXPlaceDetails object collected by your custom UI"
)

使用保存的卡支

使用 AWXPaymentConsent 支付

paymentSessionHandler.startConsentPayment(with: "payment consent")

使用 consent ID 支付 - 仅当卡以网络令牌形式保存时使用这种支付方式

paymentSessionHandler.startConsentPayment(withId: "consent ID")

使用 Apple Pay 支付

Important

请确保您已正确设置 Apple Pay

paymentSessionHandler.startApplePay()

使用跳转支付

Important

您应在 additionalInfo 中提供 "/api/v1/pa/config/payment_method_types/${payment method name}" 中指定的所有必填字段

paymentSessionHandler.startRedirectPayment(
    with: "payment method name",
    additionalInfo: "all required information"
)

处理支付结果

您可以统一在 AWXPaymentResultDelegate 的回调中处理 UI集成或 Low-Level API集成支付的结果。

func paymentViewController(_ controller: UIViewController?, didCompleteWith status: AirwallexPaymentStatus, error: Error?) {
    // call back for status success/in progress/ failure / cancel
}

Tip

如果在支付过程中创建了 consent，您可以通过此可选函数以获取 consent ID 以供后续使用。

func paymentViewController(_ controller: UIViewController?, didCompleteWithPaymentConsentId paymentConsentId: String) {
    // To do anything with this ID.
}

贡献

我们欢迎任何形式的贡献，包括新功能、错误修复和文档改进。最好的贡献方式是提交拉取请求——我们会尽快回复您的补丁。如果您发现错误或有任何问题，也可以提交问题。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Airwallex iOS SDK

概述

开始集成

要求

示例项目

集成步骤

安装

Swift Package Manager

CocoaPods

必要设置

Customer ID

创建 `AWXSession`

创建 `AWXPaymentIntent`

设置客户端密钥

可选设置

微信支付

Apple Pay

UI 集成

启动完整支付列表（推荐）

仅展示卡支付

按名称启动支付方式

自定义主题色

Low-level API 集成

创建 PaymentSessionHandler

使用卡支付

使用保存的卡支

使用 Apple Pay 支付

使用跳转支付

处理支付结果

贡献

FilesExpand file tree

README_zh_CN.md

Latest commit

History

README_zh_CN.md

File metadata and controls

Airwallex iOS SDK

概述

开始集成

要求

示例项目

集成步骤

安装

Swift Package Manager

CocoaPods

必要设置

Customer ID

创建 AWXSession

创建 AWXPaymentIntent

设置客户端密钥

可选设置

微信支付

Apple Pay

UI 集成

启动完整支付列表（推荐）

仅展示卡支付

按名称启动支付方式

自定义主题色

Low-level API 集成

创建 PaymentSessionHandler

使用卡支付

使用保存的卡支

使用 Apple Pay 支付

使用跳转支付

处理支付结果

贡献

创建 `AWXSession`

创建 `AWXPaymentIntent`