Fiserv 在 iPhone SDK 上的 Tap to Pay

目的

此包是一个软件开发包 (SDK)，简化了在您的应用程序中启用 Apple 在 iPhone 上的 Tap To Pay 功能。只需进行少量配置和几行代码，您的 iPhone 应用程序就可以在支持的 iPhone 上安全地接受非接触式支付，而无需任何额外硬件（例如 POS 终端、外部卡读卡器设备等）
当前此功能仅在美国可用。通过使用此包，您将 不需要 认证您的应用程序。我们已经为您处理了这一点。

先决条件

设备要求

Apple Tap to Pay on iPhone 需要 iPhone XS 或更高版本，运行 iOS 16 或更高版本

Tap to Pay 授权

您必须向 Apple 请求特殊的授权才能启用 Tap To Pay。登录到您的 Apple 开发者账户，然后点击此处请求授权。在标题为 'PSP' 的文本框中输入 'Fiserv'。按照以下说明为您应用程序的配置文件添加授权

获取 Fiserv 认证信息

您可以通过按以下步骤在 Fiserv 开发者工作室获取您应用程序的测试认证信息：

点击页面右上角的橙色按钮创建账户
使用您的电子邮件地址/密码登录到 Developer Studio
在顶部的工具栏中点击 'Workspaces' 选项
点击 '添加新的工作区' 按钮
创建一个类型为 'CommerceHub' 的工作区。提供名称和描述，然后从 'Product' 下拉列表中选择 'CommerceHub'
点击 '创建' 按钮
在工作区中，点击 'Credentials' 选项卡
点击 '创建 API 密钥'。您需要从下拉列表中选择一个商户 ID，为 API 密钥提供名称，从 'API 密钥类型' 列表中选择 'Sandbox' 单选按钮，并在 '功能' 复选框中选择 'Payments'。点击 '创建' 按钮。
重要！复制完整 API 密钥和密码并 安全地保存。或者，您可以点击 '保存到文件' 按钮将它们下载到文件中。您需要这些凭据来访问 Fiserv SDK 和后端 API。在您的代码和应用程序中保护这些凭据。

入门

创建一个新的项目或打开您现有的应用程序在 XCode。按照以下说明将 Fiserv 包添加到您的应用程序中

在 Xcode 中打开您的应用程序，选择 File -> Add Packages...
在屏幕右上方的搜索栏中，输入包 URL：https://github.com/Fiserv/TTPPackage
点击屏幕底部的 '添加包' 按钮
再次点击 '添加包'。该包将被下载并添加到您的项目中

配置卡读卡器

创建一个 FiservTTPConfig 实例，并按以下方式加载您的配置：

let myConfig = FiservTTPConfig(
    secretKey: "<your secret key from Developer Studio>",
    apiKey: "<your API key from Developer Studio>",
    environment: .Sandbox,
    currencyCode: "USD",
    appleTtpMerchantId: "<optional apple ttp merchantId provided by fiserv>",
    merchantId: "<your merchantId from the CommerceHub workspace on Developer Studio>",
    merchantName: "<your merchant name as it will be displayed in the Tap to Pay payment sheet>",
    merchantCategoryCode: "<your MCC>",
    terminalId: "10000001", /// Identifies the specific device or point of entry where the transaction originated assigned by the acquirer or the gateway
    terminalProfileId: "3c00e000-a00e-2043-6d63-936859000002") /// Unique identifier for the terminal profile used to configure the kernels of the card reader and manage payment terminal behavior

现在创建一个 FiservTTPCardReader 类型的实例，它是您的应用程序将与之交互的主要类。通常您会将此放入视图模型中。

private let fiservTTPCardReader: FiservTTPCardReader = FiservTTPCardReader(configuration: myConfig)

在您的应用程序启动过程中早期，调用以下方法以验证运行您应用程序的设备是否支持iPhone上的Apple Tap To Pay：

if !fiservTTPCardReader.readerIsSupported() {
    ///TODO handle unsupported device
}

获取PSP令牌

您必须获取一个会话令牌才能使用SDK。通过以下调用获取令牌：

do {
    try await fiservTTPCardReader.requestSessionToken()
} catch let error as FiservTTPCardReaderError {
    ///TODO handle exception
}

注意，会话令牌将在24小时后过期。您需要跟踪何时获取新的令牌。

链接账户

接下来，您必须将运行应用程序的设备链接到Apple ID。这需要一次性完成。您需要跟踪链接过程是否已经发生。如果没有发生，请通过以下调用执行链接：

do {
    try await fiservTTPCardReader.linkAcount()
} catch let error as FiservTTPCardReaderError {
    ///TODO handle exception
}

初始化卡读取会话

现在，您可以通过调用以下方法来初始化Apple近距离读取器：

do {
    try await fiservTTPCardReader.activateReader()
} catch let error as FiservTTPCardReaderError {
    ///TODO handle exception
}

**注意**：每次应用程序启动和/或回到前台时，您必须重新初始化读取器会话！

接受付款

恭喜您在这个过程中取得进展！现在您已准备好处理您的第一笔付款。只需调用此方法，SDK将为您处理余下操作：

let amount = 10.99  // amount to charge
let merchantOrderId = "your order ID, for tracking purposes"
let merchantTransactionId = "your transaction ID, for tracking purposes"

do {
    let chargeResponse = try await readCard(
        amount: amount, 
        merchantOrderId: merchantOrderId, 
        merchantTransactionId: merchantTransactionId)
    ///TODO inspect the chargeResponse to see the authorization result
} catch let error as FiservTTPCardReaderError {
    ///TODO handle exception
}

取消付款

let amount = 10.99 // amount to void
let referenceTransactionId = "this value was returned in the charge response"
do {
  let voidResponse = try await voidTransaction(
      amount:amount,
      referenceTransactionId = referenceTransactionId)
    ///TODO inspect the voidResponse to see the result   
} catch let error as FiservTTPCardReaderError {
    ///TODO handle exception
}

退款付款

let amount = 10.99 // amount to void
let referenceTransactionId = "this value was returned in the charge response"
do {
  let refundResponse = try await refundTransaction(
      amount:amount,
      referenceTransactionId = referenceTransactionId)
    ///TODO inspect the refundResponse to see the result   
} catch let error as FiservTTPCardReaderError {
    ///TODO handle exception
}