PayKit for iOS

Pay Kit 是一个开源软件框架，允许您在您的应用程序中接收 Cash App Pay。该框架提供了一些模块，可以直接使用，其中客户将从您的结账体验中重定向到 Cash App 进行支付审批，然后再返回到您的应用程序。它由两个 SPM 包组成，可以分别导入。

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

• PayKitUI: 提供框架中使用到的视图。这些视图被提供给用户以启动 Pay Kit 支付并显示 Cashtag，但不规定它们的使用方式。

目录

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

要求

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

入门

• 网站
• 文档

安装（选项一）：SPM

您可以通过 SPM 安装 Pay Kit。创建一个新的 Xcode 项目，然后转到 文件 > Swift 包 > 添加包依赖。输入 URL https://github.com/cashapp/cash-app-pay-ios-sdk，然后点击 下一步。选择 main 分支，在下一个屏幕上，根据需要选择包。

安装（选项二）：CocoaPods

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

PayKit

CashAppPayObserver

CashAppPayObserver 协议只包含一个方法

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

您的实现应切换到状态参数并处理适当的状态变化。其中一些状态仅用于信息，但大多数驱动集成逻辑。下面列出了最关键的状态处理

实现URL处理

要使用Pay Kit iOS，Cash App必须能够调用一个将返回到你的应用的URL。最简单的方法是通过 自定义URL方案，但如果你的应用支持 通用链接，你也可以使用这些链接。

为你的应用程序选择一个唯一的方案，并在Xcode中从应用的“信息”标签中的目标注册。

将使用此方案（或你的应用处理的通用链接）的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]
                    )
                }
            }
        }
}

实例化 CashAppPay

当你准备使用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
        )
    )
}

你的观察器的状态将更改为 .creatingCustomerRequest，然后变为 .readyToAuthorize，此时关联的值为创建的 CustomerRequest 结构。

授权客户请求

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

示例

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

你的应用将转接到Cash App进行授权。授权完成后，你的重定向URL将被调用，发布 RedirectNotification。SDK将获取你授权的请求并将其作为状态更改为 .approved 的一部分返回给你的观察器。

将授权传递给后端并创建付款

批准的 CustomerRequest 将与 Grants 相关联，可使用Cash App的 Create Payment API。将这些授权传递给你的后端，并通过一次服务器到服务器的调用调用 CreatePayment API以完成付款。

PayKitUI

PayKitUI 提供了在 UIKit 和 SwiftUI 中都可以使用的未管理 CashAppPayButton 和 CashAppPaymentMethod 视图。

所有视图都接受一个 SizingCategory 以指定期望的视图大小。它们还默认支持浅色/深色主题。

我们不希望你对这些视图进行任何修改。

CashAppPayButton

以下是一个 CashAppPayButton 的示例

您可以按照以下方式实例化按钮

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

CashAppPaymentMethod

以下是一个 CashAppPaymentMethod 的示例

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

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

获取帮助

Github是我们的主要Pay Kit论坛。要获取帮助，请打开有关疑问、问题或想法的 问题。

许可证

本项目是根据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.