PayKit for iOS
Pay Kit 是一个开放的软件开发框架，允许您在您的应用程序中接受 Cash App Pay。该框架提供了一些可以即用模块，其中客户将从您的结账体验中转到 Cash App 进行支付批准，然后再返回到您的应用程序。它由两个单独导入的 SPM 包组成。
-
PayKit: 这是开始构建应用程序的最佳位置。《PayKit》提供了一个名为CashAppPayObserver的协议，该协议接收 Pay Kit 的更新。您的结账视图控制器可以符合此协议，或者您可以创建一个专门的观察器类。 -
PayKitUI: 提供框架中使用的视图。这些视图提供给用户以启动 Pay Kit 支付并显示 Cashtag，但并未指定如何使用它们。
目录
需求
PayKit主框架代码库支持iOS，需要Xcode 12.0或更高版本。《PayKit》框架的基本SDK版本为13.0。
入门指南
安装（选项一）：SPM
您可以通过SPM安装Pay Kit。创建一个新的Xcode项目，然后转到文件 > Swift Packages > 添加包依赖。输入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
}您的实现应该根据状态参数进行切换并处理适当的状态变化。其中一些状态仅提供信息，但大多数驱动您的集成逻辑。下面列出了需要处理的最关键状态：
| 状态 | 描述 |
|---|---|
ReadyToAuthorize |
在您的 UI 中显示 Cash App Pay 按钮，当它被点击时调用 authorizeCustomerRequest() |
Approved |
授权费用已准备好供您的后端使用以创建支付 |
Declined |
客户已拒绝 Cash App Pay 授权，必须从头开始流程或选择其他支付方式 |
| 错误状态 | |
.integrationError |
集成中的可修复错误 |
.apiError |
Cash App Pay 服务器 API 的退化。您的应用应该暂时隐藏 Cash App Pay 功能 |
.unexpectedError |
正常流程之外的错误。向 Cash App 开发者支持报告此错误（及导致它的原因） |
实现 URL 处理
要使用 Pay Kit iOS，Cash App 必须能够调用一个会回到您的应用的 URL。最简单的方法是通过 自定义 URL 方案来实现，但如果您的应用支持 通用链接，也可以使用这些 URL。
为您的应用程序选择一个唯一的方案，并在 Xcode 应用程序的“目标”的“信息”标签中进行注册。
您将为 createCustomerRequest() 方法传递一个使用此方案（或您应用处理的通用链接）的 URL，以启动授权过程。
当你的应用被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授权支付时，
- 使用你的Client ID实例化SDK
- SDK默认指向
production端点；对于开发，请将端点设置为sandbox - 将您的观察者添加到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的创建支付 API。将这些授权传递到您的后端，并通过服务器端到服务器调用调用CreatePayment API以完成支付。
PayKitUI
PayKitUI提供了在iOS 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.