Straal SDK for iOS written in Swift. A brilliant payment solution for disruptive businesses.
特性
Straal for iOS 是一个辅助库,旨在简化从商家的移动 iOS 应用程序直接发起 API 请求的操作。它利用客户端加密并通过 HTTPS 发送数据,以创建安全的请求,进行交易和添加卡片。
要求
Straal SDK 需要部署目标为 iOS 13.0+ 和 Xcode 11.0+。
后端
您还需要一个后端服务,它会处理支付信息并为应用程序创建 CryptKeys
。更多信息,请参阅Straal API 参考文档。
您的后端服务需要在 https://_base_url_/straal/v1/cryptkeys
实现至少一个端点。此端点由 SDK 用于获取用于加密敏感用户数据的 CryptKeys
。要自定义获取您的 CryptKey
的路径,您可以使用 StraalConfiguration
。
您的后端需要授权用户并可拒绝必要的
CryptKey
获取。
返回URL方案
我们的SDK执行外部3D-Secure用户验证(它支持3ds-v2)。一旦交易得到验证,我们需要一种方式从用户浏览器(或任何其他验证银行应用)返回到您的应用程序。配置应用程序中的通用链接需要几个步骤。
- 在Xcode中,点击项目导航器中的您的项目,然后转到App目标下的“信息”。
- 在“URL类型”下添加一个新的类型。
- 将其命名为“Payment”(标识符)。您的“URL方案”是最重要的部分。使用一个全局唯一的方案。一个好的候选方案是您的应用程序包标识符加上“ payments”后缀。例如:
com.company.app.payments
。 - 现在,iOS将处理该URL方案,因此我们可以将3D-Secure操作重定向回应用程序。
- 在在运行时初始化时,务必将确切的URL方案传递给
StraalConfiguration
。
然后,您需要让Straal知道在3DS过程中外部的用户活动。为此,请向您的 SceneDelegate
添加一个方法
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
URLContexts.forEach { context in
Straal.handle(context.url)
}
}
如果您使用的是Swift UI的 App
,请在主 WindowGroup
视图中添加一个 onOpenURL
处理程序,如下所示
var body: some Scene {
WindowGroup {
MyAwesomeView()
.onOpenURL(perform: { url in
Straal.handle(url)
})
}
}
这将允许Straal关闭进行3DS处理所需的任何 SFSafariViewController
视图控制器。
安装
CocoaPods
CocoaPods 是一个Cocoa项目的依赖关系管理器。您可以使用以下命令安装它
$ gem install cocoapods
要使用CocoaPods将Straal集成到您的项目中,请在您的 Podfile
中指定它
pod 'Straal', '~> 1.0.0'
然后,运行以下命令
$ pod install
Carthage
Carthage 是一个去中心化的依赖关系管理器,用于构建您的依赖项并为您提供二进制框架。
要使用Carthage将Straal集成到您的项目中,请在您的 Cartfile
中指定它
github "straal/straal-ios" ~> 1.0.0
运行carthage update --use-xcframeworks
以构建框架,并将构建好的Straal.framework
拖放到您的Xcode项目中。
Swift包管理器
Swift包管理器是一种用于管理Swift包分发工具。它与Swift构建系统和Xcode集成。
要使用Swift包管理器将Straal集成到您的项目中,请将其添加到您的Xcode项目或Package.swift
文件中。
dependencies: [
.package(url: "https://github.com/straal/straal-ios.git", .upToNextMajor(from: "1.0.0"))
]
用法
概述
要为iOS使用Straal,您需要自己的后端服务和希望用来接受支付的iOS应用。
此SDK允许您在应用中实现安全的支付过程。您的用户的敏感数据(如信用卡号码)将从移动应用程序直接发送,因此不会有卡片数据触及您的服务器。这提高了安全性,并且PCI合规性要求更少。
此过程的安全性由CryptKey
机制确保。您的商家后端服务负责通过配置中的headers
对应用程序用户进行特定CryptKey
操作的授权。
初始配置
首先,创建一个StraalConfiguration
对象(它包含您的商家URL和授权头)。然后,使用配置创建您的Straal
对象。
您还可以添加额外的cryptKeyPath
,这将是我们用于获取新的加密密钥的后端服务的URL。如果您不为这里提供值,我们将使用默认值https://_base_url_/straal/v1/cryptkeys
。
let url = URL(string: "https://your-merchant-backend-url.com")!
let returnURLScheme = "com.company.app.payments" // For more instructions see above
let headers = ["x-user-token": myUserToken] // You have to authorize your user on cryptkeys endpoint using this header!
let configuration = StraalConfiguration(baseUrl: url, returnURLScheme: returnURLScheme, headers: headers)
let straal = Straal(configuration: configuration)
注意:当您的应用需要更改授权头(用户注销或登录)时,您需要创建一个新的
Straal
对象。Straal
和StraalConfiguration
对象不是为了重复使用或更改而设计的。
一旦您有了Straal
对象,您就可以向其中提交Operations
。
操作
创建卡片
第一个操作是CreateCard
。
//You should get those from your UI inputs
let name = CardholderName(fullName: "John Appleseed")
let cvv = CVV(rawValue: "000")
let expiry = Expiry(month: "04", year: "2021")
let number = CardNumber(rawValue: "5555 5555 5555 4444")
//Now create a card object. You can optionally validate a card.
let card = Card(name: name, number: number, cvv: cvv, expiry: expiry)
// Initialise a create card operation
let createCardOperation = CreateCard(card: card)
// Now you can submit the operation for execution
straal.perform(operation: createCardOperation) { (response, error) in
// handle error and react to the response
}
注意调用此最后方法时后台发生的操作。首先,在
cryptkeys
端点使用此POST
请求获取您的商家后端:
{
"permission": "v1.cards.create"
}
您的后端的工作是验证此请求(使用传递给 StraalConfiguration
的头部),将此 JSON 与 customer_uuid
键值对附加,并将其转发给 Straal 使用 此方法。
然后,信用卡数据被加密,直接发送给 Straal,由 Straal 处理,并响应。
使用卡片创建交易
第二个支持的操作是CreateTransactionWithCard
。
let card = ...
let transaction = Transaction(amount: 200, currency: "usd", reference: "order:92830948i98y")!
let transactionWithCardOperation = CreateTransactionWithCard(card: card, transaction: transaction)
straal.perform(operation: transactionWithCardOperation) { (response, error) in
// handle error and react to the response
}
同样地,我们首先获取您的
cryptkeys
端点以获取CryptKey
。这次带上 JSON
{
"permission": "v1.transactions.create_with_card",
"transaction": {
"amount": 200,
"currency": "usd",
"reference": "order:92830948i98y"
}
}
验证交易金额(可能使用
reference
与订单配对)和用户授权属于您的后端责任。
初始化 3D-Secure
第三个支持的操作是Init3DS
。
/// First, create a Card and a Transaction.
let card: Card = ...
let transaction: Transaction = Transaction(amount: 200, currency: "usd")!
let init3DSOperation = Init3DSOperation(card: card, transaction: transaction) { [weak self] controller in
// This will be called when 3DS is initiated by Straal. Present the controller (UIViewController) passed by Straal to the user, whichever way suits your workflow and design pattern.
self?.present(controller, animated: true)
} dismiss3DSViewController: { controller in
// This will be called when 3DS is completed. Do not rely on this method being called, as the viewcontroller can be dismissed in other ways (when cancelled by the user)
controller.dismiss(animated: true, completion: nil)
}
straal.perform(operation: operation) { (response, error) in
// This will be called once the user completes 3DS and the controller dismisses, or cancels it.
// This does NOT mean that the transaction succeeded. It indicates the success or failure of 3DS itself.
// You must communicate with your backend service to be informed about trasaction status (it still needs to be completed)
// TODO: Handle the response and error
}
同样地,我们首先获取您的
cryptkeys
端点以获取CryptKey
。这次带上 JSON
{
"permission": "v1.customers.authentications_3ds.init_3ds",
"transaction": {
"amount": 200,
"currency": "usd",
"success_url": "https://your-merchant-backend-url/x-callback-url/straal/success",
"failure_url": "https://your-merchant-backend-url/x-callback-url/straal/failure"
}
}
3DS 视图控制器会扫描失败和成功 URL,因此请勿更改它们,否则我们将无法关闭它。
验证交易金额(可能使用
reference
与订单配对)和用户授权属于您的后端责任。
验证
即将推出
支持
欢迎提出建议或技术问题报告!请联系我们邮箱:[点击这里]。
许可证
本项目采用Apache License 2.0许可证发布。更多信息请参阅LICENSE。