CheckoutSDK-iOS 0.0.91

CheckoutSDK-iOS 0.0.91

Osama Rabie 维护。



 
依赖项
TapUIKit-iOS>= 0
TapNetworkKit-iOS>= 0
TapApplicationV2>= 0
SwiftyRSA>= 0
TapKeychain>= 0
BugfenderSDK= 1.11.0
 

  • O Rabie

CheckoutSDK-iOS

Tap payments 为您提供了一次性解决方案,以在您的 iOS 应用流程中实现无缝的结账过程。

访问所有本地、区域和全球的支付方式

您的客户可以通过提供中东、北非(MENA)地区所有流行的支付方式(包括Mada、KNET、Fawry、Apple Pay、Visa、Mastercard、Amex、Tabby 等)来拓展全球市场。

来看看吧!


安装

CocoaPods

将此配置项添加到您的 podfile

pod "CheckoutSDK-iOS "


预 SDK 设置

如果您已有 Tap 账户,请跳过此部分。

为了能够使用 SDK,您必须首先创建一个 Tap 账户。一旦您与我们的 集成团队完成账户,请确保他们为您提供以下内容:

  1. 您的沙箱公钥。
    1. 这将用于在我们的沙箱环境中执行测试交易。对您的开发阶段将很有用。
  2. 您的生产公钥。
    1. 这将用于在我们的生产环境中执行实际交易。在发布您的应用之前需要您提供。
  3. 您的 tap 商户 ID。
    1. 这将是用于您的 Tap 账户下的应用实体的标识符。由于您可以在同一 Tap 账户下集成多个应用/网站,因此非常有用。
  4. Apple 支付 CSR。
    1. 如果您愿意启用 Apple 支付,您必须提供您的 Apple 商户 ID,并且他们将提供 Apple 支付 CSR,您将使用它生成 Apple 支付证书,然后必须将其反馈给他们。

Apple 支付设置

如果您不愿意启用 Apple 支付,请跳过此部分。

  1. 从 Tap 团队请求 CSR。

  2. 在您的 Apple 开发者账户中

    1. 创建商户标识符

      一个 商户标识符 可以为 Apple Pay 唯一标识您为能够接受支付的有效商户。您可以为多个原生和 Web 应用使用相同的商户标识符。它永远不会过期。

      1. 证书、标识符和配置文件 中,从侧边栏中选择标识符,然后单击左上角的上加号按钮(+)。 img
      2. 选择商户标识符,然后单击继续。 img
      3. 输入商户描述和标识名称,然后点击“继续”。 img
      4. 检查设置,然后点击“注册”。
    2. 创建支付处理证书:一个 支付处理证书 与您的商户标识关联,并用于加密支付信息。支付处理证书每25个月过期。如果证书被吊销,您可以创建新的。

      1. 证书、标识符和配置文件 中,从侧边栏中选择“标识符”。img

      2. 在“标识符”下,使用右上角的过滤器选择“商户ID”。

      3. 在右侧,选择您的商户标识。

        注意: 如果页面顶部出现提示您需要接受协议的消息,请点击“审查协议”按钮,并根据说明操作后再继续。

      4. 在“Apple Pay支付处理证书”下,点击“创建证书”。

      5. 在Mac上 创建证书签名请求,然后点击“继续”。

      6. 点击“选择文件”。

      7. 在出现的对话框中,选择证书请求文件(一个扩展名为 .certSigningRequest 的文件),然后点击“选择”。

      8. 点击“继续”。

      9. 点击“下载”。

        证书文件(一个扩展名为 .cer 的文件)出现在您的“下载”文件夹中。

  3. 将您的.cer文件、商户标识和app包标识分享回Tap团队。

  4. 从Xcode将Apple Pay功能 enabling到您的项目中,并选择商户标识。 img

  5. 如果

    1. 您已完成所有前面的步骤。
    2. 客户使用我们这边启用了Apple Pay选项的货币进行支付。
    3. 支付的客户已激活其设备中的Apple Pay。
    4. 支付的客户已将其Apple Wallet中至少一张有效银行卡与我们的Apple Pay支付网络相连接。

重要信息

支持的语言

  1. 英语。
  2. 阿拉伯语。

支持的主题

SDK自动检测设备显示模式为亮色或暗色,并相应地显示。

  1. 亮色模式。
    1. Checkout SDK将以亮色模式显示,图标将着色。
  2. 亮色模式(单色)。
    1. Checkout SDK将以亮色模式显示,图标将单调色。
  3. 暗色模式。
    1. Checkout SDK将以暗色模式显示,图标将白色。
  4. 暗色模式(彩色)。
    1. Checkout SDK将以暗色模式显示,图标将彩色。

支持SDK模式

  1. 沙盒环境
    1. 在这里您可以无限制地尝试所有不同的支付方式,不会产生任何费用。
    2. 请参阅我们的测试卡
  2. 生产环境
    1. 在这里您可以尝试所有不同的支付方式,以模拟您期望的客户体验。请注意,这需要使用真实数据并可能产生费用。

支持的交易模式

  1. 购买
    1. 当您想要从您的客户那里扣除金额时使用。
  2. 授权
    1. 当您想要冻结您的客户的金额时使用。

SDK 配置

全局变量配置

这些变量需要在开始使用 Checkout SDK 之前进行设置。这将定义配置和主题化 Checkout SDK 的重要参数。请注意,未配置这些变量将会使用默认值,或者 Checkout SDK 无法启动并会抛出错误。

  1. 所需的本地化。
    1. 通过此方法,您可以定义 Checkout SDK 所使用的语言。
    2. 目前支持: en & ar
    3. 未设置时的默认值是: en
    4. 如何设置: TapLocalisationManager.shared.localisationLocale = "en" TapCheckout.localeIdentifier = "en"
  2. 所需的 Tap 密钥。
    1. 通过这种方式,您可以为 SDK 定义您的 Tap 密钥,以便 SDK 可以识别您为商家。
    2. 这些都是必需的。
    3. 如何设置: TapCheckout.secretKey = .init(sandbox: "", production:"")
  3. 可选的主题变量
    1. 当显示浅色主题时显示单色变体
      1. 如果不传递,则默认值为 false
      2. 如何设置: TapCheckout.displayMonoLight = false
    2. 当显示深色主题时显示彩色变体
      1. 如果不传递,则默认值为 false
      2. 如何设置: TapCheckout.displayColoredDark = false

启动 Checkout SDK

Checkout SDK实例

import CheckoutSDK_iOS
    class ViewController: UIViewController {
    	/// A strong reference to tap checkout variable
    	let checkout:TapCheckout = .init()
    }

Checkout SDK交易配置

/**
     Defines the tap checkout bottom sheet controller
     - Parameter delegate: A protocol to communicate with the Presente tap sheet controller
     - Parameter currency: Represents the original transaction currency stated by the merchant on checkout start
     - Parameter supportedCurrencies: Represents the allowed currencies for the transaction. Leave nil for ALL, pass the 3 digits iso KWD, EGP, etc.
     - Parameter amount: Represents the original total transaction amount stated by the merchant on checkout start
     - Parameter items: Represents the List of payment items if any. If no items are provided one will be created by default as PAY TO [MERCHANT NAME] -- Total value
     - Parameter applePayMerchantID: The Apple pay merchant id to be used inside the apple pay kit
     - Parameter onCheckOutReady: This will be called once the checkout is ready so you can use it to present it or cancel it
     - Parameter paymentType: The allowed payment type inclyding cards, apple pay, web and telecom or ALL
     - Parameter transactionMode: Decide which transaction mode will be used in this call. Purchase, Authorization, Card Saving and Toknization. Please check [TransactionMode](x-source-tag://TransactionModeEnum)
     - Parameter customer: Decides which customer is performing this transaction. It will help you as a merchant to define the payer afterwards. Please check [TapCustomer](x-source-tag://TapCustomer)
     - Parameter destinations: Decides which destination(s) this transaction's amount should split to. Please check [Destination](x-source-tag://Destination)
     - Parameter tapMerchantID: Optional. Useful when you have multiple Tap accounts and would like to do the `switch` on the fly within the single app.
     - Parameter taxes: Optional. List of Taxes you want to apply to the order if any.
     - Parameter shipping: Optional. List of Shipping you want to apply to the order if any.
     - Parameter allowedCadTypes: Decides the allowed card types whether Credit or Debit or All. If not set all will be accepeted.
     - Parameter postURL: The URL that will be called by Tap system notifying that payment has succeed or failed.
     - Parameter paymentDescription: Description of the payment to use for further analysis and processing in reports.
     - Parameter TapMetadata: Additional information you would like to pass along with the transaction. Please check [TapMetaData](x-source-tag://TapMetaData)
     - Parameter paymentReference: Implement this property to keep a reference to the transaction on your backend. Please check [Reference](x-source-tag://Reference)
     - Parameter paymentStatementDescriptor: Description of the payment  to appear on your settlemenets statement.
     - Parameter require3DSecure: Defines if you want to apply 3DS for this transaction. By default it is set to true.
     - Parameter receiptSettings: Defines how you want to notify about the status of transaction reciept by email, sms or both. Please check [Receipt](x-source-tag://Receipt)
     - Parameter authorizeAction: Defines what to do with the authorized amount after being authorized for a certain time interval. Please check [AuthorizeAction](x-source-tag://AuthorizeAction)
     - Parameter allowsToSaveSameCardMoreThanOnce: Defines if same card can be saved more than once. Default is `true`.
     - Parameter enableSaveCard: Defines if the customer can save his card for upcoming payments. Default is `true`.
     - Parameter isSaveCardSwitchOnByDefault: Defines if save card switch is on by default.. Default is `true`.
     - Parameter sdkMode: Defines the mode sandbox or production the sdk will perform this transaction on. Please check [SDKMode](x-source-tag://SDKMode)
     - Parameter collectCreditCardName: Decides whether or not, the card input should collect the card holder name. Default is false
     - Parameter creditCardNameEditable: Decides whether or not, the card name field will be editable
     - Parameter creditCardNamePreload: Decides whether or not, the card name field should be prefilled
     - Parameter isSubscription: Defines if you want to make a subscription based transaction. Default is false
     - Parameter recurringPaymentRequest: Defines the recurring payment request Please check [Apple Pay
     docs](https://developer.apple.com/documentation/passkit/pkrecurringpaymentrequest). NOTE: This will only be availble for iOS 16+ and subscripion parameter is on.
     - Parameter applePayButtonType: Defines the type of the apple pay button like Pay with or Subscripe with  etc. Default is Pay
     - Parameter applePayButtonStyle: Defines the UI of the apple pay button white, black or outlined. Default is black
     - Parameter showSaveCreditCard:Decides whether or not, the card input should show save card option for Tap and Merchant sides. Default is None
     - Parameter shouldFlipCardData: Defines if the card info textfields should support RTL in Arabic mode or not
     */
	 
checkout.build(
            delegate: self,
            currency: .KWD,
            supportedCurrencies: [TapCurrencyCode.EGP.appleRawValue, TapCurrencyCode.KWD.appleRawValue],
            amount: 100,
            items: [.init(title: "Item Title", description: "Item Description", price: 100, quantity: 1, discount: nil, taxes: [], currency: .KWD)],
            applePayMerchantID: "merchant.tap.gosell",
            paymentType: .All,
            transactionMode: .purchase,
            customer: try! .init(emailAddress: .init(emailAddressString: "[email protected]"), phoneNumber: .init(isdNumber: "965", phoneNumber: "50000000"), name: "Customer Name", address: nil),
            tapMerchantID: TapFormSettingsViewController.merchantSettings().3,
            taxes: [],
            shipping: nil,//.init(name: "Optional shipping fees", amount: 20),
            require3DSecure: true,
            sdkMode: .sandbox,
            collectCreditCardName: true,
            creditCardNameEditable: true,
            creditCardNamePreload: "",
            showSaveCreditCard: .Merchant,
            isSubscription: false,
            recurringPaymentRequest: nil,
            applePayButtonType: .PayWithApplePay,
            applePayButtonStyle: .Auto,
            shouldFlipCardData: false,
            onCheckOutReady: {[weak self] tapCheckOut in
                DispatchQueue.main.async() {
                    tapCheckOut.start(presentIn: self)
                }
            })

变量深入观察

让我们仔细看看配置Checkout SDK的变量。

变量 示例值 默认值 说明
currency .KWD .USD 表示启动结账时由商家声明的原始交易货币
supportedCurrencies [TapCurrencyCode.EGP/appleRawValue, TapCurrencyCode.KWD/appleRawValue] nil 表示允许的交易货币。留nil表示所有货币,传递3位iso KWD,EGP等。
amount 100.12 1 表示启动结账时由商家声明的原始总交易金额
items [.init(title: "商品标题", description: "商品描述", price: 100, quantity: 1, discount: nil, taxes: [], currency: .KWD)] [] 表示如果有任何支付项目,表示支付项目列表。如果没有提供项目,将默认创建一个为“付给[MERCHANT NAME] -- 总值”的项目
applePayMerchantID "merchant.gosell" "" 在Apple Pay kit中使用的Apple Pay商家id。您可以从您的Apple开发者账户中获取此值。有关更多详细信息,请参阅Apple Pay部分
paymentType .CARD .All 表示您想启用哪个支付方法组。我们目前有: .All, .Web, . Card, .Device
transactionMode .purchase .purchase 决定在此调用中使用哪种交易模式。我们目前有
customer try! .init(identifier: "cus_TS031720211012r4RM0403926") try! .init(identifier: "cus_TS031720211012r4RM0403926") 决定哪个客户正在执行此交易。这将帮助您作为商家定义之后付款人
destinations [目标标识符 (标识符: "destID",数量:10,货币:.科威特第纳尔)] nil 决定这个交易的金额应该分给哪个目标。
tapMerchantID "11233" nil 您应用的 Tap 标识符。请从 Tap 的集成团队获取它。
税项 [.init (标题:"增值税",描述:"税",金额:.init (类型:.固定,值:10))] nil 希望添加到您的交易价值之上的任何税项值。
运费 .init (名称:"运费",金额:10) nil 代表您想在交易中添加的任何额外运费价值。
允许的卡类型 [CardType (cardType: .Debit)] [CardType (cardType: .All)] 确定允许的卡类型,是信用卡还是借记卡或全部。如果没有设置,都将被接受。
postURL URL(string: "") nil 如果提供了该 URL,Tap 后端将在交易结果发出一个 post 请求。
paymentDescription "paymentDescription" nil 支付描述,有助于将其与您的数据库相关联。
paymentMetadata "["key1":"value1"]" nil 附加到交易的额外数据,用于您的目的。
paymentStatementDescriptor "paymentStatementDescriptor" nil 付款描述,将显示在账单上。
require3DSecure true true 这将告诉我们在使用信用卡付款时是否必须强制执行3D安全。请注意,即使传递为false,但如果发卡行银行要求,则仍将显示 3DS。
receiptSettings Receipt(email: true, sms: true) nil 指示通过向客户发送电子邮件或短信来告知客户交易的方式。
authorizeAction AuthorizeAction.capture(after: 24) AuthorizeAction.default 指示 X 时间后对已授权金额的操作。我们目前有 AuthorizeAction.capture & AuthorizeAction.void
enableSaveCard true true 是否想要显示 "保存卡" 选项。
isSaveCardSwitchOnByDefault true true 是否自动选择 "保存卡" 选项。
sdkMode .sandbox .sandbox 你想要开发的环境。
collectCreditCardName true false 是否在客户使用信用卡付款时收集卡片名称。
creditCardNameEditable true true 是否允许您的客户在付款时编辑卡名称字段。
creditCardNamePreload "Tap Payments" "" 如果您想将值放入卡名称字段,可以在这里传递。

CheckoutScreenDelegate

此列表根据您的上下文可以监听回调以从 Checkout SDK 获取所需的数据/事件。

/// Inform the delegate that we may need log some strings for further analysis
    @objc optional func log(string:String)
    
    /**
     Will be fired just before the sheet is dismissed
     */
    @objc optional func tapBottomSheetWillDismiss()
    /**
     Will be fired once the controller is presented
     */
    @objc optional func tapBottomSheetPresented(viewController:UIViewController?)
    /**
     Will be fired once the checkout fails for any error
     */
    @objc optional func checkoutFailed(in session:URLSessionDataTask?, for result:[String:String]?, with error:Error?)
    
    /**
     Will be fired once the charge (CAPTURE) successfully transacted
     */
    @objc(checkoutChargeCaptured:) optional func checkoutCaptured(with charge:Charge)
    
    /**
     Will be fired once the charge (AUTHORIZE) successfully transacted
     */
    @objc(checkoutAuthorizeCaptured:) optional func checkoutCaptured(with authorize:Authorize)
    
    /**
     Will be fired once the charge (CAPTURE) successfully transacted
     */
    @objc(checkoutChargeFailed:) optional func checkoutFailed(with charge:Charge)
    
    /**
     Will be fired once the charge (AUTHORIZE) successfully transacted
     */
    @objc(checkoutAuthorizeFailed:) optional func checkoutFailed(with authorize:Authorize)
    
    
    /**
     Will be fired once the card is succesfully tokenized
     */
    @objc optional func cardTokenized(with token:Token)
    
    
    /**
     Will be fired once apply pay tokenization fails
     */
    @objc optional func applePayTokenizationFailed(in session:URLSessionDataTask?, for result:[String:String]?, with error:Error?)
    
    /**
     Will be fired once card tokenization fails
     */
    @objc optional func cardTokenizationFailed(in session:URLSessionDataTask?, for result:[String:String]?, with error:Error?)
    
    /**
     Will be fired once save card tokenization fails
     */
    @objc optional func saveCardTokenizationFailed(in session:URLSessionDataTask?, for result:[String:String]?, with error:Error?)
    
    /**
     Will be fired once the save card is done
     */
    @objc optional func saveCardSuccessfull(with savedCard:TapCreateCardVerificationResponseModel)
    
    /**
     Will be fired once the save card failed
     */
    @objc optional func saveCardFailed(with savedCard:TapCreateCardVerificationResponseModel)

接收付款的最少代码

Swift

/** To start a transaction you only need to pass these
1. Your Tap keys.
2. Amount.
3. Currency.
4. Customer.
*/
TapCheckout.secretKey = .init(sandbox: "", production:"")
        let checkout:TapCheckout = .init()
        checkout.build(
            delegate:self,
            currency: .KWD,
            amount: 10,
            customer: try! .init(emailAddress: .init(emailAddressString: "[email protected]"), phoneNumber: nil, name: "TAP CUSTOMER", address: nil),
            onCheckOutReady: {[weak self] tapCheckOut in
                DispatchQueue.main.async() {
                    tapCheckOut.start(presentIn: self)
                }
            }
        )

Objective-C

使用我们的付款按钮

上述代码展示了如何展示我们的 Checkout SDK,作为一个通用操作,您可以从任何 UI 元素中嵌入/触发。我们还提供了 付款按钮,它将显示 付款 + 自定义加载器,这是一个您可以放在您的 UIView 中的 UI 元素。

类参数

/// The outlet reference for the Tap button you have inside your story board.
@IBOutlet weak var tapPayButton: TapActionButton!
/// The pay button view model. That will be used to construct and listen to events fired from the button.
let tapPayButtonViewModel:TapPayButtonViewModel = .init()

配置支付按钮

/// A sample code that sets up the button with the view model, set the status of the button & define the action to be called when the button is clicked.
func adjustTapButton() {
        tapPayButton.setup(with: tapPayButtonViewModel)
        tapPayButtonViewModel.buttonStatus = .ValidPayment
        tapPayButtonViewModel.buttonActionBlock = { [weak self] in 
			self?.startSDKClicked()
			self?.tapPayButtonViewModel.startLoading()
			self?.startCheckoutSDK()
		}
    }

结束Tap按钮的加载状态

/// Just expand
tapPayButtonViewModel.expandButton()
/// You can end loading by showing a status and do logic on completion
tapPayButtonViewModel.endLoading(with: false) {
            self.tapBottomSheetWillDismiss()
            var message = "No error message"
            if let result = result {
                message = ""
                result.tap_allKeys.forEach{ message = "\(message)\n\($0) : \(result[$0] ?? "")" }
            }
            
            if let error = error {
                message = "\(message)\n\(error.localizedDescription)"
            }
            self.showAlert(title: "Error", message: message)
        }