BlueSnap iOS SDK概述

BlueSnap的iOS SDK使您能够轻松地将iOS应用中的信用卡支付直接进行处理，然后通过BlueSnap的支付API进行处理。此外，如果您使用以下描述的标准结账流程，您还可以处理Apple Pay和PayPal支付。当您使用此库时，BlueSnap会为您处理大部分PCI合规负担，因为用户的支付数据被标记化并直接发送到BlueSnap。

本文将涵盖以下主题

• 结账流程选项
• 安装
• 用法
• 使用BlueSnap SDK UI实现标准结账流程
• 实现自定义结账流程
• 使用您自己的UI实现标准结账流程
• 3D Secure身份验证
• 发送支付进行处理
• 示例应用程序 - 解释
• 参考

结账流程选项

BlueSnap iOS SDK提供三种优雅的结账流程供您选择。

使用BlueSnap SDK UI实现标准结账流程

此流程允许您快速使用我们预先构建的结账UI开始操作，使您能够在您的应用程序中接受信用卡、Apple Pay 和 PayPal 支付。其中包括以下功能：

• 指定所需用户信息，例如电子邮件或账单地址。
• 预先填充结账页面。
• 指定回应用户，以便 BlueSnap 可以预先填充结账界面中的他们的支付和送货/账单信息。
• 使用简单的启动函数启动结账UI。
• 内置 3D secure 身份验证。
• 定期付款、购物者配置和订阅费。

要查看标准结账流程的图像，请点击这里。

自定义结账流程

自定义结账流程使您能够轻松地使用我们灵活的信用卡UI组件接受信用卡支付，让您能够完全控制结账体验的外观和感觉。其中包括以下功能：

• 灵活可定制的UI元素，内置验证和卡类型检测。
• 辅助类可帮助您进行货币转换、删除空格等。
• 简单的功能，可提交敏感的卡详细信息直接发送到 BlueSnap 服务器。
• 内置 3D secure 身份验证。
• 定期付款、购物者配置和订阅费。

要查看信用卡UI组件的图像，请点击这里。

使用您自己的UI实现标准结账流程

此流程允许您构建自己的结账UI。请注意，使用您自己的UI，您将需要通过使用 BlueSnapService 类执行API调用来处理传输到 BlueSnap 的数据。其中包括以下功能：

• 辅助类可帮助您进行输入验证、货币转换、删除空格等。
• 简单的功能，可提交敏感的卡详细信息直接发送到 BlueSnap 服务器。
• 启用3D secure身份验证的简单基础设施。
• 定期付款、购物者配置和订阅费。

安装

SDK是用 Swift 5 编写的，使用 Xcode 14.3.1。

需求

• Xcode 10+
• BlueSnap API凭据

BluesnapSDK期望在您的产品包中有一个包含BlueSnap API凭据的.plist文件。请注意，文件可以只有一个物理实例，其余的实例可以被Xcode引用。

.plist文件必须命名为credentials.plist，并且它必须在plist的根目录包含2个字符串：BsAPIUser和BsAPIPassword（它们在plist中出现的顺序不重要）。

CocoaPods（可选，CocoaPods 1.1.0+）

CocoaPods是Cocoa项目的依赖管理器。您可以使用以下命令安装它

$ gem install cocoapods

要使用CocoaPods将BluesnapSDK集成到Xcode项目中，请在其Podfile中指定它

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'BluesnapSDK', '~> <git tag/branch name>' 
    pod 'BluesnapSDK/DataCollector', '~> <git tag/branch name>'

end

然后运行以下命令

$ pod install

使用.xcworkspace文件打开Xcode中的项目。

SPM（可选）

要使用SPM将BluesnapSDK集成到Xcode项目中，请打开项目，通过选择文件 -> 添加包依赖项打开SPM对话框。在SPM对话框打开后，在搜索栏中输入仓库的URL，然后点击添加包。注意：当Xcode提示您选择要导入的包时，您必须在你的项目中使用Kount，否则您也必须选择KountWrapper包，因为由于SPM的限制，KountWrapper是BluesnapSDK在本例中的直接依赖包，并且两者必须一起使用。

禁用横屏模式

我们的用户界面不支持横屏模式，因此为了确保屏幕不会随设备旋转，您需要在应用程序的 AppDelegate.swift 文件中添加此代码

// MARK: Prevent auto-rotate
func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
    return UIInterfaceOrientationMask(rawValue: UIInterfaceOrientationMask.portrait.rawValue)
}

Apple Pay（可选）

在标准结账流程中，Apple Pay 可用于您的应用程序。您需要创建新的 Apple Pay 证书、Apple 商户 ID 并在 Xcode 中配置 Apple Pay。有关详细信息，请参阅我们提供的Apple Pay 指南。

SDK 将激活 Apple Pay UI 并从购物者处收集付款详情。然后收集 pkpayment 令牌并将其加密传递到 Bluesnap 服务器。您不需要在移动应用程序或服务器中自行处理 applepay 令牌，只需像往常一样通过服务器到服务器的调用完成交易即可。请注意，示例应用程序在模拟器上运行时无法完成演示的服务器到服务器的调用。这需要物理设备。

PayPal（可选）

在标准结账流程中，您可以选择在您的应用程序中接受 PayPal 付款。请按照以下步骤操作

1. 请确保您拥有 PayPal 商业或专业账户。如果您还没有 PayPal 账户，您可以在 PayPal 网站上注册一个。

2. 将 PayPal 账户连接到 BlueSnap。有关详细信息，请参阅此处。

使用说明

本部分将涉及以下主题

• 生成交易令牌
• 初始化SDK

生成交易令牌

对于每个交易，您需要生成一个托管支付字段令牌并在服务器上传递给SDK。

为此，使用您的API凭证启动一个服务器到服务器的POST请求，并将其发送到Sandbox或生产环境的相关URL

• Sandbox: https://sandbox.bluesnap.com/services/2/payment-fields-tokens
• 生产: https://ws.bluesnap.com/services/2/payment-fields-tokens

指定回应用户
要指定回应用户并让BlueSnap预先填充检查页面的信息，请在URL查询字符串中包含参数shopperId。例如：https://sandbox.bluesnap.com/services/2/payment-fields-tokens?shopperId=20848977

成功响应将在Location头中包含令牌。更多信息，请参见创建托管支付字段令牌。

初始化SDK

使用您的令牌字符串创建BSToken实例。

fileprivate var bsToken : BSToken?
bsToken = BSToken(tokenStr: "c3d011abe0ba877be0d903a2f0e4ca4ecc0376e042e07bdec2090610e92730b5_")

通过调用BlueSnapSDK类的initBluesnap函数，在SDK中初始化您的令牌和任何附加功能（例如Apple Pay或欺诈预防）。有关函数参数的完整列表，请参阅initBluesnap。**注意**：对于每次购买，您都需要用新令牌调用initBluesnap。

→ 如果您使用的是标准结账流程，则继续阅读下一节。
→ 如果您使用的是自定义结账流程，请转到实现自定义结账流程。

使用 BlueSnap SDK UI 实现标准结账流程

本部分将涉及以下主题

• 定义您的结账设置
• 启动结账界面

定义您的结账设置

BlueSnapSDK 类的 showCheckoutScreen 函数是 SDK 的主要入口点，应在调用 initBluesnap 之后调用。在调用时，该函数会根据您提供的参数启动用户界面。例如，您可以显示税收总额和小计，指定需要用户提供的字段，并预先填充结账页面，使用您已经收集的信息。

此函数包含以下参数。我们将在本节中介绍设置 sdkRequest。

有关 showCheckoutScreen 的更多信息，请参阅下方的参考部分。

定义 sdkRequest

sdkRequest（BSSdkRequest 的一个实例）保存您的结账设置，如价格详情、所需的用户字段，以及您已经收集的用户数据，还保存完成购买和更新税率时的回调函数。

fileprivate var sdkRequest: BSSdkRequest! = BSSdkRequest(...)

BSSdkRequest 构造函数参数

定义priceDetails

priceDetails（一个 BSPriceDetails 的实例）是 sdkRequest 的属性，它包含关于金额、税款金额和货币的属性。设置这些属性以初始化结账页面的价格详情。

sdkRequest.priceDetails = BSPriceDetails(amount: 25.00, taxAmount: 1.52, currency: "USD")

如果您接受PayPal支付，请注意：只有当 currency 设置为您的PayPal配置中支持的货币时，PayPal才会可用。

预填充结账页面（可选）

sdkRequest 的以下属性允许您传递关于用户的信息以预填充结账页面。

在演示应用的 ViewController.swift 文件中，查看 setInitialShopperDetails 函数，了解如何使用用户数据设置这些属性。

处理税收更新（可选）

如果您选择收集运费详情（即 withShipping 设置为 true），那么在用户更改他们的运货地址时，您可能想更新税率。向 sdkRequest 的 updateTaxFunc 属性提供一个回调函数来处理税收更新。当用户更改他们的运货国家或州时，您的函数将被调用。要查看示例，请检查演示应用中的 updateTax。

定义您的购买回调函数

purchaseFunc 是 sdkRequest 的一个成员，它接受一个回调函数，在用户点击“支付”并且他们的数据成功提交给 Bluesnap（并与您的令牌相关联）后被调用。purchaseFunc 将用以下类实例之一进行调用（如果且仅当向 Bluesnap 的数据提交成功）

• 如果结果是 BSApplePaySdkResult 实例，它将包含关于金额、税费和货币的详细信息。请注意，没有收集账单/运货信息，因为它对于完成购买不是必需的。

• 如果结果是 BSCcSdkResult 或 BSExistingCcSdkResult 实例，它将包含关于金额、税费、货币、运货/账单信息、3D Secure 身份验证结果以及非敏感的信用卡详情（卡类型、最后四位数字、发行国家）的信息。

• 如果结果是 BSPayPalSdkResult，那么交易已经完成！您不需要将交易发送到您的服务器进行处理。

以下逻辑应在 purchaseFunc 中应用

1. 检测用户选择的特定支付方式。

2. 如果用户选择了 PayPal，无需采取进一步行动 - 交易已完成。显示成功消息。

3. 如果用户选择了 Apple Pay 或信用卡，使用订单详情和令牌更新您的服务器。除非您需要保留非安全的信用卡详情，否则处理信用卡或 Apple Pay 没有真正的区别。您只需要令牌来最终完成交易。

4. 从您的服务器，使用您的令牌完成购买。

5. 在收到 Bluesnap 的响应后，更新客户端并向用户显示适当的消息。

演示应用中的 completePurchase 函数显示了此逻辑。

private func completePurchase(purchaseDetails: BSBaseSdkResult!) {

    if let paypalPurchaseDetails = purchaseDetails as? BSPayPalSdkResult {
        // user chose PayPal
        // show success message
        return // no need to complete purchase via BlueSnap API
    }

    // handle Apple-Pay or Credit card:
    // send order details & bsToken to server...
    // ...receive response

    // depending on response, show success/fail message
}

备注:

• purchaseFunc 只有在用户详情成功提交到 BlueSnap 后才会被调用。在发生错误的情况下，将不会调用它。

• 从您的服务器发送付款进行处理非常重要。

启动结账界面

既然您已经设置了 showCheckoutScreen 的参数，是时候为用户启动结账界面了。

    BlueSnapSDK.showCheckoutScreen(
        inNavigationController: self.navigationController,
        animated: true,
        sdkRequest: sdkRequest
    )

一切就绪！接受苹果支付、信用卡和 PayPal 付款将变得十分简单。

配置购物流程

BlueSnap SDK 提供了一种简单的流程来收集购物者的信息和选择的支付方式。此流程将用于您希望注册时保存购物者的支付细节，并在以后快速方便地使用的应用程序中。此流程只能为现有购物者运行（您可以使用 BlueSnap API 轻松创建购物者）。如果购物者选择信用卡，我们将收集账单细节并在 BlueSnap 服务器上存储，以便（以后的）收费将不需要购物者输入任何信息。如果购物者选择 Google Pay 或 PayPal，我们只需保留此首选项，以便在下一步（创建支付流程）中，购物者将自动收到 ApplePay 弹出窗口或 PayPal 页面。

为了运行此流程，您需要创建一个 BSSdkRequestShopperRequirements 实例，而不是 sdkRequest，并启动 showChoosePaymentScreen 而不是 showCheckoutScreen。在 purchaseFunc 中，您无需进行任何更进一步的操作，因为此阶段只涉及保存细节。

使用所选支付方式支付流程

BlueSnap SDK 提供了一种简便的方式，可以使用现有购物者的所选支付方式创建交易。在这里，您可以快速使用购物者选择的支付方式进行支付。此流程只能为具有有效选定支付详情的现有购物者运行。如果（在前一步：配置购物者流程）购物者选择了信用卡，您将立即收到响应；如果购物者选择了 ApplePay 或 PayPal，他们将现在进行支付流程。在这两种情况下，结果与常规结账流程中的结果相同：BSBaseSdkResult 返回一些（非安全）信息。

要运行此流程，您需要创建一个 sdkRequest 实例，并使用 showCreatePaymentScreen 代替 showCheckoutScreen。在 purchaseFunc 中，您需要完成交易，这与常规结账流程完全相同——现在您主要需要让您的应用服务器向 BlueSnap 发起 API 调用，仅发送令牌，交易即可完成。在 PayPal 的情况下，您甚至不需要这么做，因为 PayPal 流程已经完成了交易。

重要：对于每一笔新购买，您都需要生成一个新令牌，使用您的令牌和任何其他附加参数调用 initBluesnap，然后按照此顺序调用 showCheckoutScreen。

实现自定义结账流程

本部分将涉及以下主题

• 配置 BSCcInputLine
• 设置 BSCcInputLineDelegate
• 设置您的提交操作

配置 BSCcInputLine

BSCcInputLine 是一个 UIView，它包含用户的敏感信用卡数据——信用卡号、到期日期和 CVV。除了提供优雅的用户体验外，它还处理输入验证，并将加密数据提交给 BlueSnap。只需在您的故事板中放置一个 UIView 并将其类设置为 BSCcInputLine 即可。

备注:

• 除了卡信息外，请确保收集在 此页面 上标有 必需 的用户信息。
• 如果您想为信用卡号、到期日期和 CVV 自己构建 UI 字段，BlueSnap 提供了一个名为 submitTokenizedDetails 的函数来直接将用户的卡数据提交给 BlueSnap。请访问 参考部分 了解更多。

设置 BSCcInputLineDelegate

如果您使用 BSCcInputLine 来收集用户数据，在您的 ViewController 中您需要实现 BSCcInputLineDelegate，它有 6 个方法

* 在 didSubmitCreditCard 中，您将执行以下操作

1. 检测用户的卡数据是否已成功提交到 BlueSnap（即错误为 nil）。

2. 如果错误为 nil，您将在 creditCard 中得到 CC 类型、发行国家和 CC 号码的最后 4 位。更新您的服务器。

3. 从您的服务器，您将使用您的 token 发送支付请求。

4. 收到 BlueSnap 的响应后，您将更新客户端并显示适当的消息给您的用户（例如，“恭喜，您的支付成功！”或“哎呀，请重试。”）。

设置您的提交操作

在提交操作（例如，当用户在结账时提交付款）时，您应该调用 BSCcInputLine 的 validate 函数以确保数据正确。如果验证成功（即 validate 返回 true），然后调用 BSCcInputLine 的 submitPaymentFields() 函数，该函数将使用提交的结果调用 didSubmitCreditCard 回调。

另一个选项是调用 checkCreditCard(ccn: String)，该函数首先验证然后提交详细信息，在成功提交后调用代理 didSubmitCreditCard。

使用自己的 UI 实现标准结账流程

本部分将涉及以下主题

• 收集所有付款信息
• 生成一个 BSTokenizeRequest 实例
• 将详细信息提交到 BlueSnap 服务器
• 处理 3D Secure 身份验证

您需要自己创建 UI 布局文件和活动。请使用以下提供的实体和方法来实现业务逻辑

收集所有付款信息

使用自己的 UI 从购物者那里收集所有付款信息。您可以使用 辅助类 进行输入验证、货币转换、删除空白字符等。

生成一个 BSTokenizeRequest 实例

• 在信用卡购买的情况下

BSTokenizeRequest 实例需要将购买详情传递给 BlueSnap 服务器。对象包含以下属性

• paymentDetails - 购物者的信用卡信息
• billingDetails - 购物者的账单信息
• shippingDetails - 购物者的配送信息

paymentDetails 属性

如果你是提交一张新信用卡（无论是新用户还是现有用户），你应该创建一个 BSTokenizeNewCCDetails 并存储其所有属性。

如果你是提交一张现有信用卡（对于现有用户和之前已提交并存储的信用卡），你应该创建一个 BSTokenizeExistingCCDetails 并存储其所有属性。

向 BlueSnap 服务器提交详细信息

使用 BlueSnapSDK 的 submitTokenizedDetails 来提交商家的详细信息。

处理 3D 安全身份验证

BlueSnap SDK 集成了 Cardinal SDK 来提供对 3D 安全身份验证的全面处理。

使用 BlueSnapSDK 的 authenticationWith3DS 来调用身份验证。

提交支付进行处理

如果商家通过 PayPal 购买，则交易已成功提交，无需采取进一步行动。

如果购物者是通过信用卡购买的，您需要使用服务器端到服务器端API调用来创建交易，调用BlueSnap支付API，并使用SDK中初始化的托管支付字段令牌。您应该在购物者完成结账并离开SDK结账屏幕后进行此操作。请访问API文档了解更多信息。

在订阅结账的情况下，您应该使用服务器到服务器端API调用来创建订阅，这也在API文档中有介绍。

注意：在标准结账流程中，这是调用purchaseFunc的时候。在自定义结账流程中，这是调用didSubmitCreditCard的时候（如果使用BSCcInputLine字段），或者调用completion的时候（如果使用您自己的输入字段）。

示例应用程序的DemoTransactions.swift文件展示了授权捕获请求的示例。请注意，这些调用仅用于演示目的 - 交易应该从您的服务器发送。

3D Secure身份验证

SDK包含了集成的Cardinal SDK用于3DS身份验证。

如果您使用BlueSnap SDK UI：如果您选择激活此服务且购物者选择信用卡作为支付方式，3DS身份验证结果将在调用sdkRequest的purchaseFunc时作为SdkResult的一部分传递。您可以像这样访问它

    let threeDSResult = (purchaseDetails as? BSCcSdkResult)?.threeDSAuthenticationResult

如果您使用自己的UI：Cardinal结果将在authenticationWith3DS回调函数中可用。

如果3DS身份验证成功，结果将是以下之一

• AUTHENTICATION_SUCCEEDED = 3D Secure身份验证成功，因为购物者正确地输入了他们的凭证，或者发行行在不需要购物者身份验证的情况下对交易进行了验证。
• AUTHENTICATION_BYPASSED = 由于商家的配置，跳过了3D Secure身份验证。

如果3DS身份验证未成功，结果将是以下错误之一

• AUTHENTICATION_UNAVAILABLE = 对于此张卡，3D Secure身份验证不可用。
• AUTHENTICATION_FAILED = 在Cardinal挑战中卡验证失败。
• THREE_DS_ERROR = 发生了Cardinal内部错误或服务器错误。
• CARD_NOT_SUPPORTED = 由于不支持的3DS版本，未执行3D Secure挑战。
• AUTHENTICATION_CANCELED（仅在使用自己的UI时）= 购物者取消了挑战或按下了Cardinal活动中的'返回'按钮。

在这种情况下，您可以决定是否要继续执行交易而不进行3DS身份验证。请注意，只有当在BlueSnap控制台中的设置 > 防欺诈设置中启用了**处理失败的3DS交易**选项时，您才能继续交易。

示例应用 - 解释

示例应用展示了如何使用标准结账流程的基本功能，包括您需要实现的各个阶段（所有内容都在ViewController类中）。

示例应用凭证

示例应用需要使用沙箱API凭证来模拟商户服务器的操作，您可以从中获得Bluesnap沙箱仪表板的沙箱API凭证。这些凭证通过环境变量注入到Configuration.swift中，或者出于演示目的可直接放置在那里。您可以在shell中放置环境变量或在Configuration.swift中编写它们。凭证将被打印到示例应用日志中。

注意
为了让Xcode将环境变量传递给构建过程，您需要明确使用以下命令行进行设置

defaults write com.apple.dt.Xcode UseSanitizedBuildSystemEnvironment -bool NO

环境变量在示例应用的info.plist中配置，请参见${BS_API_USER} ${BS_API_PASSWORD}

虽然这种方法对示例应用来说是可以的，但它不应该在实际场景中使用。不要将API凭证留在您的应用代码中。

基本步骤包括

1. 从BlueSnap的服务器获取令牌。请注意，您需要从您的服务器进行此操作。在示例应用中，我们使用从BlueSnap沙箱环境创建的虚拟凭证创建令牌。根据UI中的切换，我们可以创建带购物者ID的令牌（用于返回用户流程）或没有购物者ID的令牌（用于新用户流程）。

2. 调用BlueSnapSDK.initBluesnap来初始化令牌以及任何额外的设置，例如欺诈检测或令牌过期回调函数。

3. 通过创建一个BSSdkRequest实例并填充您可能已经知道的用户信息的部分（通过设置shippingDetails和billingDetails），提供您的税计算回调，并指定您希望从用户那里获取的字段（通过设置withShipping、fullBilling和withEmail）来初始化结账流程的输入。

4. 定义purchaseFunc回调以调用您的应用服务以完成购买（请参见定义您的购买回调函数以了解此函数的逻辑）。

5. 调用BlueSnapSDK.showCheckoutScreen以启动用户的结账UI。

注意：示例应用展示了如何利用我们的货币屏幕，允许用户在结账期间更改货币选择，通过使用关联参数调用BlueSnapSDK.showCurrencyList。
重要：所有交易调用仅用于演示目的。这些调用应从您的服务器进行。

参考

本部分将涉及以下主题

• 数据结构
• 主要功能 - BlueSnapSDK类
• 处理令牌过期
• 辅助类
• 自定义UI控件

数据结构

在BlueSnap iOS SDK项目中，Model 组包含整个项目中使用的数据结构。

BSToken (在BSToken.swift中)

BSToken是最简单的一个。它包含从BlueSnap接收到的令牌，以便SDK可以带着它调用BlueSnap API。

public class BSToken {
    internal var tokenStr: String! = ""
    internal var serverUrl: String! = ""
    public init(tokenStr : String!) {
        ...
    }
    public func getTokenStr() -> String! {
        return self.tokenStr
    }    
    public func getServerUrl() -> String! {
        return self.serverUrl
    }
}

SDK提供了一个从我们的沙箱环境中获取令牌以进行快速测试的函数。

BSSdkRequest (在BSPurchaseModelData.swift中)

此类允许您初始化您的结账设置，例如价格详情、必需的用户字段和您已经收集的用户数据。

有关BSSdkRequest属性的更多信息，请参阅定义sdkRequest。

@objc public class BSSdkRequest : NSObject {
    public var withEmail: Bool = true
    public var withShipping: Bool = false
    public var fullBilling : Bool = false

    public var priceDetails: BSPriceDetails! = BSPriceDetails(amount: 0, taxAmount: 0, currency: nil)
    
    public var billingDetails : BSBillingAddressDetails?
    public var shippingDetails : BSShippingAddressDetails?
    public var purchaseFunc: (BSBaseSdkResult!) -> Void
    public var updateTaxFunc: ((_ shippingCountry: String, _ shippingState: String?, _ priceDetails: BSPriceDetails) -> Void)?
    
    public init(
            withEmail: Bool,
            withShipping: Bool,
            fullBilling: Bool,
            priceDetails: BSPriceDetails!,
            billingDetails: BSBillingAddressDetails?,
            shippingDetails: BSShippingAddressDetails?,
            purchaseFunc: @escaping (BSBaseSdkResult!) -> Void,
            updateTaxFunc: ((_ shippingCountry: String, _ shippingState: String?, _ priceDetails: BSPriceDetails) -> Void)?) {
            ...
    }
}

BSPriceDetails（在 BSPurchaseDataModel.swift 中）

该类包含既为购买输入也为输出的价格详情，例如金额、税费金额和货币。

@objc public class BSPriceDetails : NSObject, NSCopying {
    
    public var amount : Double! = 0.0
    public var taxAmount : Double! = 0.0
    public var currency : String! = "USD"
    
    public init(amount : Double!, taxAmount : Double!, currency : String?) {
        super.init()
        self.amount = amount
        self.taxAmount = taxAmount
        self.currency = currency ?? "USD"
    }
    
    public func copy(with zone: NSZone? = nil) -> Any {
        let copy = BSPriceDetails(amount: amount, taxAmount: taxAmount, currency: currency)
        return copy
    }
    
    public func changeCurrencyAndConvertAmounts(newCurrency: BSCurrency!) {
        ...
    }
}

BSBaseAddressDetails、BSBillingAddressDetails、BSShippingAddressDetails（在 BSAddress.swift 中）

这些类包含用户的账单和运输详情。可选/必选

• 只有当 BSInitialData 中的 withEmail 设置为 true 时，才会收集电子邮件。
• 只有当国家有州（美国、加拿大和巴西）时，州才是必选项。
• 除了没有邮政/邮编的国家外，邮编总是必选项。
• 如果不使用完整的账单选项，则名称、国家和邮编是必需的，而电子邮件是可选的。
• 对于完整的账单详情，一切都是必选项。
• 对于运输详情，除电话外所有字段都是必选项。

public class BSBaseAddressDetails {

    public init() {}

    public var name : String! = ""
    public var address : String?
    public var city : String?
    public var zip : String?
    public var country : String?
    public var state : String?

    public func getSplitName() -> (firstName: String, lastName: String)? {
        return BSStringUtils.splitName(name)
    }
}

public class BSBillingAddressDetails : BSBaseAddressDetails {

    public override init() { super.init() }
    public var email : String?
}

public class BSShippingAddressDetails : BSBaseAddressDetails {

    public override init() { super.init() }
    public var phone : String?
}

BSPaymentType（在 BSPurchaseDataModel.swift 中）

此枚举区分用户选择的支付方式。它将包含信用卡、Apple Pay 和 PayPal 的案例。

public enum BSPaymentType {
    case CreditCard = "CC"
    case ApplePay = "APPLE_PAY"
    case PayPal = "PAYPAL"
}

BSBaseSdkResult（在 BSPurchaseDataModel.swift 中）

核心数据结构是这个类（及其派生类），它存储由SDK收集的用户数据，即购买详情。这是该类的简略版本。

public class BSBaseSdkResult : NSObject {
    
    var fraudSessionId: String?
    var priceDetails: BSPriceDetails!
        
    internal init(sdkRequest: BSSdkRequest) {
        ...
    }

// Returns the fraud session ID used in KountInit()
    public func getFraudSessionId() -> String? {
        return fraudSessionId;
    }
    
    /*
    Set amounts will reset the currency and amounts, including the original amounts.
    */
    public func setAmountsAndCurrency(amount: Double!, taxAmount: Double?, currency: String) {
    ...
    }
     
    // MARK: getters and setters
    
    public func getAmount() -> Double! {
        return priceDetails.amount
    }
    
    public func getTaxAmount() -> Double! {
        return priceDetails.taxAmount
    }
    
    public func getCurrency() -> String! {
        return priceDetails.currency
    }
}

BSCcSdkResult（在BSCcPayment.swift中）

此类继承自BSBaseSdkResult，并存储领新信用卡流程中收集的数据。

public class BSCcSdkResult : BSBaseSdkResult {
    
    public var creditCard: BSCreditCard = BSCreditCard()
    public var billingDetails : BSBillingAddressDetails! = BSBillingAddressDetails()
    public var shippingDetails : BSShippingAddressDetails?
    public var threeDSAuthenticationResult: String!
    
    public override init(sdkRequest: BSSdkRequest) {
        ...
    }
...
}

BSExistingCcSdkResult（在BSCcPayment.swift中）

此类继承自BSCcSdkResult，并在回访用户选择现有信用卡时存储收集的数据。它存储的数据与父类相同。

public class BSExistingCcPaymentRequest : BSCcPaymentRequest, NSCopying {
        
    ...
}

BSCreditCard（在BSCcPayment.swift中）

该类包含用户购买的非敏感信用卡详细信息，包括信用卡类型、信用卡号最后四位和发行国家。

@objc public class BSCreditCard : NSObject, NSCopying {
    
    // these fields are output - result of submitting the CC details to BlueSnap
    public var ccType : String?
    public var last4Digits : String?
    public var ccIssuingCountry : String?
        public var expirationMonth: String?
        public var expirationYear: String?
    ...
}

BSApplePaySdkResult（在BSApplePayPayment.swift中）

此类继承自BSBaseSdkResult，并存储ApplePay流程中收集的数据（目前没有任何数据）。

public class BSApplePaySdkResult: BSBaseSdkResult {
    
    public override init(sdkRequest: sdkRequest) {
        ...
    }
}

BSPayPalSdkResult (位于 BSPayPalPayment.swift 中)

这个类继承自 BSBaseSdkResult，它包含了 PayPal 过程中收集的数据，仅为发票 ID。

public class BSPayPalSdkResult: BSBaseSdkResult {
    
    public var payPalInvoiceId : String?
    
    override public init(sdkRequest: sdkRequest) {
    ...
    }
}

主要功能 - BlueSnapSDK 类

BlueSnapSDK 类包含了 SDK 的主要功能。在本节中，我们将介绍该类包含的每个函数。

initBluesnap

这是您需要调用的第一个函数，用于初始化 SDK 中的 token、防欺诈、Apple Pay 等。注意：token 有效期为 60 分钟或交易完成后（以先到者为准）。

签名

open class func initBluesnap(
        bsToken : BSToken!,
        generateTokenFunc: @escaping (_ completion: @escaping (BSToken?, BSErrors?) -> Void) -> Void,
        initKount: Bool,
        fraudSessionId: String?,
        applePayMerchantIdentifier: String?,
    merchantStoreCurrency : String?,
        completion: @escaping (BSErrors?)->Void) {

备注

• initBluesnap 是异步的，可能需要几秒钟。它的 completion 参数是您提供的回调函数，将在初始化完成后调用。确保在此发生之前不要开始结账流程。
  
• 令牌在60分钟后或在使用令牌处理支付后失效（二者以先到者为准）。因此，您需要为每一笔购买生成一个新的令牌。当你在generateTokenFunc参数中提供回调函数时，这将被自动处理（参见处理令牌过期）。

初始化防欺诈

调用initBluesnap时传递initKount: true，以初始化SDK的防欺诈功能。将收集关于用户设备的数据以进行欺诈分析。如果您有fraudSessionId，可以将其传递。如果没有，可以传递nil（空）以让BlueSnap为您生成一个。更多信息请参阅开发者文档。

配置Apple Pay（可选）

在调用initBluesnap时设置您的Apple Pay商户ID，通过传递参数applePayMerchantIdentifier。

setBsToken

此函数用于处理令牌过期。在从BlueSnap收到新令牌后，将其调用以在SDK中设置您的令牌（注意：要在流程开始时初始化令牌，请调用initBluesnap）。

签名

open class func setBsToken(bsToken: BSToken!)

令牌在60分钟后或在交易完成后失效（以先到者为准）。

显示结账屏幕

这是标准结账流程的 主要功能（你将在调用 initBluesnap 完成后调用它）。一旦你调用 showCheckoutScreen，SDK 就会为用户提供结账流程。

签名

open class func showCheckoutScreen(
    inNavigationController: UINavigationController!,
    animated: Bool,
    sdkRequest : BSSdkRequest!)

参数

BSSdkRequestSubscriptionCharge (订阅流程)

这是对 BSSdkRequest 的扩展，用于启用订阅支持，在订阅流程中使用此对象。此对象构造函数允许你实例化一个不包含价格详情的 Sdk 请求，这对于此类流程是合适的。

提交令牌化详情

当您使用自己的输入字段收集用户数据时，此函数是相关的。调用 submitTokenizedDetails 后，会将用户数据提交给 BlueSnap，它与您的令牌相关联。

重要：不要将原始信用卡数据发送到您的服务器。使用此功能从客户端直接将敏感数据提交给 BlueSnap。

签名

open class func submitTokenizedDetails(tokenizeRequest: BSTokenizeRequest, completion: @escaping ([String:String], BSErrors?) -> Void)

参数

您的 completion 回调应执行以下操作

1. 检测用户的卡数据是否已成功提交给 BlueSnap（如果 BSErrors 为 nil）。
2. 如果提交成功，您可以继续进行处理 3D 安全认证 或直接继续下一步而不进行 3DS 认证。
3. 使用您的令牌更新您的服务器交易详情。从您的服务器发送支付请求进行处理。
4. 收到BlueSnap的响应后，您将更新客户端并显示给用户适当的消息。

authenticationWith3DS

如果您使用自己的UI集成3D Secure身份验证，则此功能相关。 authenticationWith3DS 处理所有数据传输到BlueSnap和Cardinal服务器。

签名

open class func authenticationWith3DS(currency: String, amount: String, creditCardNumber: String? = nil, _ completion: @escaping (String, BSErrors?) -> Void)

参数

如果卡的3DS版本受支持并且需要验证购物者身份：Cardinal活动将被启动，购物者将被要求输入认证码。

3D Secure流程完成后，您的完成回调将被调用。

您的 completion 回调应执行以下操作

1. 处理3DS认证结果。有关3DS结果选项，请参阅3D Secure认证
2. 如果是服务器错误（THREE_DS_ERROR），则错误描述将在completion回调的BSErrors参数中可用。
3. 如果您选择继续交易，请按照以下步骤操作
4. 使用您的令牌更新您的服务器交易详情。从您的服务器发送支付请求进行处理。
5. 收到BlueSnap的响应后，您将更新客户端并显示给用户适当的消息。

createSandboxTestToken

返回BlueSnap沙盒环境的令牌，这对于测试 purposes非常有用。在您的实际应用程序中，此令牌应由您的服务器生成并发送到应用程序，以便应用程序不会暴露您的API凭据。一旦BlueSnap从服务器获得结果，完成函数将被调用。它将接收令牌或错误。

签名

open class func createSandboxTestToken(completion: @escaping (BSToken?, BSErrors?) -> Void)

createSandboxTestTokenWithShopperId

与createSandboxTestToken类似，但这里你需要提供一个购物者ID以启用回程用户流程。

签名

open class func createSandboxTestTokenWithShopperId(shopperId: Int?, completion: @escaping (BSToken?, BSErrors?) -> Void) 

处理令牌过期

你将通过向SDK提供一个回调函数来处理令牌过期。你需要将此函数作为参数传递给SDK中的generateTokenFunc，在BlueSnapSDK.initBluesnap调用过程中（有关参数的完整列表，请参见initBluesnap）。

你的回调函数应具有以下签名。在演示应用程序中，此函数被调用为generateAndSetBsToken。

func generateAndSetBsToken(completion: @escaping (_ token: BSToken?, _ error: BSErrors?)->Void)

你的函数应执行以下操作以解决令牌过期问题。

1. 调用你的服务器以生成一个新的BlueSnap令牌。
2. 通过调用BlueSnapSDK.setBsToken在SDK中初始化令牌。
3. 调用传入的完成函数。如果不这样做，原始操作将无法使用新令牌成功完成。

辅助类

这些辅助类提供了你可以利用的 additional functionality，例如字符串验证和货币转换。

字符串工具和验证

BSStringUtils (在BSStringUtils.swift中)

此工具提供了一些字符串帮助函数，如removeWhitespaces，removeNoneDigits等。

BSValidator (在 BSValidator.swift 中)

此类提供验证函数，如 isValidEmail、getCcLengthByCardType、formatCCN、getCCTypeByRegex 等，帮助您格式化信用卡信息并验证用户信息。

处理货币和汇率

这些货币结构和方法可以帮助您在结账时执行货币转换。使用 BSPriceDetails 中的函数 changeCurrencyAndConvertAmounts。

货币数据结构

我们有 2 个数据结构（见 BSCurrencyModel.swift）：BSCurrency 保存单个货币，而 BSCurrencies 保存所有货币。

public class BSCurrency {
    internal var name : String!
    internal var code : String!
    internal var rate: Double!
    ...
    public func getName() -> String! {
        return self.name
    }
    public func getCode() -> String! {
        return self.code
    }
    public func getRate() -> Double! {
        return self.rate
    }
}

public class BSCurrencies {
    ...
    public func getCurrencyByCode(code : String!) -> BSCurrency? {
        ...
    }
    public func getCurrencyIndex(code : String) -> Int? {
        ...
    }
    public func getCurrencyRateByCurrencyCode(code : String!) -> Double? {
        ...
    }
}

货币功能（在 BlueSnapSDK 类中）

getCurrencyRates

该函数返回货币及其比率的列表。值在调用 BlueSnapSDK.initBlesnap() 时获取。

签名

open class func getCurrencyRates() -> BSCurrencies?

showCurrencyList

如果您正在使用标准结账流程，可以使用此函数利用我们的货币选择屏幕，让用户选择新的货币进行支付。有关调用此函数的示例，请参阅演示应用程序的 ViewController.swift。

签名

open class func showCurrencyList(
    inNavigationController: UINavigationController!,
    animated: Bool,
    selectedCurrencyCode : String!,
    updateFunc: @escaping (BSCurrency?, BSCurrency?)->Void,
    errorFunc: @escaping()->Void
)

参数

自定义 UI 控件

如果您想构建自己的 UI，可能发现我们的自定义控件很有用，既可以用作它们本身，也可以从继承并调整以适应您自己的功能。

代码中有很多注释，解释了如何使用它们以及每个函数的作用。

它们都是 @IBDesignable UIViews，因此您可以轻松地进行检查：只需将 UIView 拖入 Storyboard 中，将类名改为以下之一，然后开始使用可检查属性进行操作。

BSBaseTextInput

BSBaseTextInput 是一个包含文本框和可选图片的 UIView，您几乎可以自定义它的所有部分。就其本身而言，它的用途有限，因为它是下面两个控件的基类。

BSInputLine

BSInputLine 是一个包含标签、文本框和可选图片的 UIView，您几乎可以自定义它的所有部分。

BSCcInputLine

BSCcInputLine 是一个包含信用卡信息字段（卡号、过期日期和 CVV）的 UIView。除了拥有酷炫的外观，它还处理自己的验证，并将安全的提交到 BlueSnap，因此您不需要在应用程序中处理它。