Straal 1.0.0

Straal 1.0.0

Michal Dabrowski 维护。



Straal 1.0.0


Platform pod License: Apache 2.0 GitHub codebeat badge Language Twitter

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)。一旦交易得到验证,我们需要一种方式从用户浏览器(或任何其他验证银行应用)返回到您的应用程序。配置应用程序中的通用链接需要几个步骤。

  1. 在Xcode中,点击项目导航器中的您的项目,然后转到App目标下的“信息”。
  2. 在“URL类型”下添加一个新的类型。
  3. 将其命名为“Payment”(标识符)。您的“URL方案”是最重要的部分。使用一个全局唯一的方案。一个好的候选方案是您的应用程序包标识符加上“ payments”后缀。例如: com.company.app.payments
  4. 现在,iOS将处理该URL方案,因此我们可以将3D-Secure操作重定向回应用程序。
  5. 在在运行时初始化时,务必将确切的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对象。StraalStraalConfiguration对象不是为了重复使用或更改而设计的。

一旦您有了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