PayKit 是一个开源软件框架，允许您在您的 App 中接受 Cash App Pay。该框架提供开箱即用的模块，客户将从您的结账体验重定向到 Cash App 以批准付款，然后再重定向回您的 App。 它由两个 SPM 包组成，每个包都可以单独导入。

• PayKit: 这是构建您的应用程序的最佳起点。PayKit 提供了一个名为 CashAppPayObserver 的协议，该协议接收来自 Pay Kit 的更新。 您的结账视图控制器可以遵循此协议，或者您可以创建一个专用的观察者类。

• PayKitUI: 提供框架中使用的视图。 这些视图提供给用户以启动 Pay Kit 付款并显示 Cashtag，但不规定必须如何使用它们。

• 要求
• 入门
  • SPM
  • Cocoapods
• PayKit
  • CashAppPayObserver
  • 实现 URL 处理
  • 实例化 CashAppPay
  • 创建客户请求
  • 授权客户请求
  • 将 Grants 传递到后端并创建付款
• PayKitUI
  • CashAppPayButton
  • CashAppPaymentMethod
• 获取帮助
• 许可证

主要的 PayKit 框架代码库支持 iOS，需要 Xcode 12.0 或更高版本。 PayKit 框架的 Base SDK 版本为 13.0。

• 网站
• 文档

您可以通过 SPM 安装 Pay Kit。 创建一个新的 Xcode 项目并导航到 File > Swift Packages > Add Package Dependency。 输入 url https://github.com/cashapp/cash-app-pay-ios-sdk 并点击 Next。 选择 main 分支，然后在下一个屏幕上，根据需要选中相应的包。

将 Cocoapods 添加到您的项目。 打开 Podfile 并添加 pod 'CashAppPayKit' 和/或 pod 'CashAppPayKitUI' 并保存您的更改。 运行 pod update，现在 Pay Kit 将通过 Cocoapods 包含在内

CashAppPayObserver 协议仅包含一个方法

func stateDidChange(to state: CashAppPayState) {
    // handle state changes
}

您的实现应该根据 state 参数进行切换，并处理适当的状态更改。 这些可能的状态中的一些仅用于信息目的，但大多数驱动您的集成的逻辑。 下表列出了要处理的最关键状态

要使用 Pay Kit iOS，Cash App 必须能够调用一个 URL，该 URL 将重定向回您的应用程序。 实现此目的的最简单方法是通过 自定义 URL 方案，但如果您的应用程序支持 通用链接，您也可以使用这些 URL。

为您的应用程序选择一个唯一的方案，并在 Xcode 中从应用程序目标的 Info 选项卡中注册它。

您将把使用此方案的 URL（或您的应用程序处理的通用链接）传递到启动授权过程的 createCustomerRequest() 方法中。

当您的应用程序被 Cash App 回调时，只需从您的 AppDelegate 或 SceneDelegate 发布 CashAppPay.RedirectNotification，SDK 将处理其余的事情

import UIKit
import PayKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
        func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
                if let url = URLContexts.first?.url {
                    NotificationCenter.default.post(
                        name: CashAppPay.RedirectNotification,
                        object: nil,
                        userInfo: [UIApplication.LaunchOptionsKey.url : url]
                    )
                }
            }
        }
}

当您准备好使用 Cash App Pay 授权付款时，

1. 使用您的客户端 ID 实例化 SDK
2. SDK 默认指向 production 端点; 对于开发，将端点设置为 sandbox
3. 将您的观察者添加到 SDK

例如，从您的实现 CashAppPayObserver 协议的结账视图控制器中，您可以将 SDK 实例化为

private let sandboxClientID = "YOUR_CLIENT_ID"
private lazy var sdk: CashAppPay = {
    let sdk = CashAppPay(clientID: sandboxClientID, endpoint: .sandbox)
    sdk.addObserver(self)
    return sdk
}()

只要您知道要收取的金额，或者您想创建一个存档付款请求，您就可以创建客户请求。 您必须在结帐视图控制器加载后立即创建此请求，以便您的客户可以毫无延迟地授权该请求。

要收取 $5.00，您的 createCustomerRequest 调用可能如下所示

private let sandboxBrandID = "YOUR_BRAND_ID"

override func viewDidLoad() {
    super.viewDidLoad()
    // load view hierarchy
    sdk.createCustomerRequest(
        params: CreateCustomerRequestParams(
            actions: [
                .oneTimePayment(
                    scopeID: brandID,
                    money: Money(amount: 500, currency: .USD)
                )
            ],
            channel: .IN_APP,
            redirectURL: URL(string: "tipmycap://callback")!,
            referenceID: nil,
            metadata: nil
        )
    )
}

您的 Observer 的状态将更改为 .creatingCustomerRequest，然后更改为 .readyToAuthorize，并将创建的 CustomerRequest 结构作为关联值。

一旦 SDK 处于 .readyToAuthorize 状态，您可以存储关联的 CustomerRequest 并显示 Cash App Pay 按钮。 当客户点击该按钮时，您可以授权客户请求。

示例

@objc func cashAppPayButtonTapped() {
   sdk.authorizeCustomerRequest(request)
}

您的应用程序将重定向到 Cash App 进行授权。 授权完成后，将调用您的重定向 URL，并且将发布 RedirectNotification。 SDK 将获取您授权的请求并将其返回给您的 Observer，作为更改为 .approved 状态的一部分。

已批准的 CustomerRequest 将具有与 Cash App 的 Create Payment API 一起使用的关联 Grants。 将这些 Grants 传递到您的后端并调用 CreatePayment API 作为服务器到服务器的调用以完成您的付款。

PayKitUI 在 UIKit 和 SwiftUI 中提供了一个非托管的 CashAppPayButton 和一个 CashAppPaymentMethod 视图。

所有视图都接受一个 SizingCategory 来指示视图在您的应用程序中的首选大小。 它们还默认支持浅色/深色主题。

我们希望您按原样使用这些视图，无需任何修改。

以下是 CashAppPayButton 的一个示例

您可以按如下方式实例化该按钮

let button = CashAppPayButton(size: .small, onClickHandler: {})

以下是 CashAppPaymentMethod 的一个示例

您可以按如下方式实例化 CashAppPaymentMethod

let paymentMethod = CashAppPaymentMethod(size: .small)
paymentMethod.cashTag = "$jack"

GitHub 是我们 Pay Kit 的主要论坛。 要获得帮助，请打开 Issues，提出问题、问题或想法。

本项目根据 Apache 2.0 许可证的条款提供。 请参阅 LICENSE 文件。

Copyright 2023 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   https://apache.ac.cn/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.