CheckoutSDK-iOS
Tap payments 为您提供了一次性解决方案,以在您的 iOS 应用流程中实现无缝的结账过程。
访问所有本地、区域和全球的支付方式
您的客户可以通过提供中东、北非(MENA)地区所有流行的支付方式(包括Mada、KNET、Fawry、Apple Pay、Visa、Mastercard、Amex、Tabby 等)来拓展全球市场。
来看看吧!
安装
CocoaPods
将此配置项添加到您的 podfile
pod "CheckoutSDK-iOS "
预 SDK 设置
如果您已有 Tap 账户,请跳过此部分。
为了能够使用 SDK,您必须首先创建一个 Tap 账户。一旦您与我们的 集成团队完成账户,请确保他们为您提供以下内容:
- 您的沙箱公钥。
- 这将用于在我们的沙箱环境中执行测试交易。对您的开发阶段将很有用。
- 您的生产公钥。
- 这将用于在我们的生产环境中执行实际交易。在发布您的应用之前需要您提供。
- 您的 tap 商户 ID。
- 这将是用于您的 Tap 账户下的应用实体的标识符。由于您可以在同一 Tap 账户下集成多个应用/网站,因此非常有用。
- Apple 支付 CSR。
- 如果您愿意启用 Apple 支付,您必须提供您的 Apple 商户 ID,并且他们将提供 Apple 支付 CSR,您将使用它生成 Apple 支付证书,然后必须将其反馈给他们。
Apple 支付设置
如果您不愿意启用 Apple 支付,请跳过此部分。
-
从 Tap 团队请求 CSR。
-
在您的 Apple 开发者账户中
-
-
创建商户标识符
一个 商户标识符 可以为 Apple Pay 唯一标识您为能够接受支付的有效商户。您可以为多个原生和 Web 应用使用相同的商户标识符。它永远不会过期。
- 在 证书、标识符和配置文件 中,从侧边栏中选择标识符,然后单击左上角的上加号按钮(+)。
- 选择商户标识符,然后单击继续。
- 输入商户描述和标识名称,然后点击“继续”。
- 检查设置,然后点击“注册”。
- 在 证书、标识符和配置文件 中,从侧边栏中选择标识符,然后单击左上角的上加号按钮(+)。
-
创建支付处理证书:一个 支付处理证书 与您的商户标识关联,并用于加密支付信息。支付处理证书每25个月过期。如果证书被吊销,您可以创建新的。
-
在 证书、标识符和配置文件 中,从侧边栏中选择“标识符”。
-
在“标识符”下,使用右上角的过滤器选择“商户ID”。
-
在右侧,选择您的商户标识。
注意: 如果页面顶部出现提示您需要接受协议的消息,请点击“审查协议”按钮,并根据说明操作后再继续。
-
在“Apple Pay支付处理证书”下,点击“创建证书”。
-
在Mac上 创建证书签名请求,然后点击“继续”。
-
点击“选择文件”。
-
在出现的对话框中,选择证书请求文件(一个扩展名为
.certSigningRequest
的文件),然后点击“选择”。 -
点击“继续”。
-
点击“下载”。
证书文件(一个扩展名为
.cer
的文件)出现在您的“下载”文件夹中。
-
-
-
将您的.cer文件、商户标识和app包标识分享回Tap团队。
-
如果
- 您已完成所有前面的步骤。
- 客户使用我们这边启用了Apple Pay选项的货币进行支付。
- 支付的客户已激活其设备中的Apple Pay。
- 支付的客户已将其Apple Wallet中至少一张有效银行卡与我们的Apple Pay支付网络相连接。
重要信息
支持的语言
- 英语。
- 阿拉伯语。
支持的主题
SDK自动检测设备显示模式为亮色或暗色,并相应地显示。
- 亮色模式。
Checkout SDK
将以亮色模式显示,图标将着色。
- 亮色模式(单色)。
Checkout SDK
将以亮色模式显示,图标将单调色。
- 暗色模式。
Checkout SDK
将以暗色模式显示,图标将白色。
- 暗色模式(彩色)。
Checkout SDK
将以暗色模式显示,图标将彩色。
支持SDK模式
- 沙盒环境
- 在这里您可以无限制地尝试所有不同的支付方式,不会产生任何费用。
- 请参阅我们的测试卡
- 生产环境
- 在这里您可以尝试所有不同的支付方式,以模拟您期望的客户体验。请注意,这需要使用真实数据并可能产生费用。
支持的交易模式
- 购买
- 当您想要从您的客户那里扣除金额时使用。
- 授权
- 当您想要冻结您的客户的金额时使用。
SDK 配置
全局变量配置
这些变量需要在开始使用 Checkout SDK
之前进行设置。这将定义配置和主题化 Checkout SDK
的重要参数。请注意,未配置这些变量将会使用默认值,或者 Checkout SDK
无法启动并会抛出错误。
- 所需的本地化。
- 通过此方法,您可以定义
Checkout SDK
所使用的语言。 - 目前支持:
en
&ar
。 - 未设置时的默认值是:
en
。 - 如何设置:
TapLocalisationManager.shared.localisationLocale = "en"
TapCheckout.localeIdentifier = "en"
- 通过此方法,您可以定义
- 所需的 Tap 密钥。
- 通过这种方式,您可以为 SDK 定义您的 Tap 密钥,以便 SDK 可以识别您为商家。
- 这些都是必需的。
- 如何设置:
TapCheckout.secretKey = .init(sandbox: "", production:"")
- 可选的主题变量
- 当显示浅色主题时显示单色变体
- 如果不传递,则默认值为
false
。 - 如何设置:
TapCheckout.displayMonoLight = false
- 如果不传递,则默认值为
- 当显示深色主题时显示彩色变体
- 如果不传递,则默认值为
false
。 - 如何设置:
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)
}