Installation
The SDK is supported on devices running iOS 14 or higher.
Ottu is available via CocoaPods. To install it, the following line must be added to the Podfile:
pod 'ottu_checkout_sdk', :git => 'https://github.com/ottuco/ottu-ios.git', :tag => '2.1.2'pod 'ottu_checkout_sdk', :git => 'https://github.com/ottuco/ottu-ios'The Swift Package Manager (SPM) is a tool designed for automating the distribution of Swift code and is integrated into the Swift compiler.
Once the Swift package has been set up, adding Alamofire as a dependency requires simply including it in the dependencies value of the Package.swift file.
dependencies: [
.package(url: "https://github.com/ottuco/ottu-ios.git", from: "2.1.2")
]The SDK UI is embedded as a View within any part of a ViewController in the merchant's application.
Example:
If only one payment option is available and it is a wallet, the UI is automatically minimized.
There are both UIKit and SwiftUI samples available at the sample repo:
The SDK initialization process and the callback delegate remain identical for both implementations.
Code Sample:
do {
self.checkout =
try Checkout(
formsOfPayments: formsOfPayment,
theme: theme,
displaySettings: PaymentOptionsDisplaySettings(
mode: paymentOptionsDisplayMode,
visibleItemsCount: visibleItemsCount,
defaultSelectedPgCode: defaultSelectedPgCode
),
sessionId: sessionId,
merchantId: merchantId,
apiKey: apiKey,
setupPreload: transactionDetailsPreload,
delegate: self
)
} catch
let error as LocalizedError {
showFailAlert(error)
return
} catch {
print("Unexpected error: \(error)")
return
}
if let paymentView = self.checkout?.paymentView() {
paymentView.translatesAutoresizingMaskIntoConstraints = false
self.paymentContainerView.addSubview(paymentView)
NSLayoutConstraint.activate([
paymentView.leadingAnchor.constraint(equalTo: self.paymentContainerView.leadingAnchor),
self.paymentContainerView.trailingAnchor.constraint(equalTo: paymentView.trailingAnchor),
paymentView.topAnchor.constraint(equalTo: self.paymentContainerView.topAnchor),
self.paymentContainerView.bottomAnchor.constraint(equalTo: paymentView.bottomAnchor)
])
}
extension OttuPaymentsViewController: OttuDelegate {
func errorCallback(_ data: [String: Any] ? ) {
paymentContainerView.isHidden = true
let alert = UIAlertController(title: "Error", message: data?.debugDescription ?? "", preferredStyle:
.alert)
alert.addAction(UIAlertAction(title: "OK", style: .cancel))
self.present(alert, animated: true)
}
func cancelCallback(_ data: [String: Any] ? ) {
var message = ""
if let paymentGatewayInfo = data ? ["payment_gateway_info"] as ? [String: Any],
let pgName = paymentGatewayInfo["pg_name"] as ? String,
pgName == "kpay" {
message = paymentGatewayInfo["pg_response"].debugDescription
} else {
message = data?.debugDescription ?? ""
}
paymentContainerView.isHidden = true
let alert = UIAlertController(title: "Canсel", message: message, preferredStyle: .alert)
alert.addAction(UIAlertAction(title: "OK", style: .cancel))
self.present(alert, animated: true)
}
func successCallback(_ data: [String: Any] ? ) {
paymentContainerView.isHidden = true
paymentSuccessfullLabel.isHidden = false
let alert = UIAlertController(title: "Success", message: data?.debugDescription ?? "", preferredStyle:
.alert)
alert.addAction(UIAlertAction(title: "OK", style: .cancel))
present(alert, animated: true)
}
}
The main class describing theme is called CheckoutTheme.
It uses additional component classes like:
ButtonComponentLabelComponentTextFieldComponent
The CheckoutTheme class consists of objects that define various UI components. While the names of these components largely correspond to those listed here, they also include platform-specific fields for further customization.
All properties in the CheckoutTheme class are optional, allowing users to customize any of them as needed.
If a property is not specified, the default value (as defined in the Figma design here) will be automatically applied.
General
Fees
Data
Other
selectPaymentMethodTitleLabel
The text of "Select Payment Method" in the bottom sheet header
inputTextField
Font and color of text in any input field (including disabled state)
backgroundColor
The main background of the SDK view component
UIColor
backgroundColorModal
The background of any modal window
UIColor
iconColor
The color of the icon of the payment
UIColor
paymentItemBackgroundColor
The background of an item in payment options list
UIColor
selectPaymentMethodTitleBackgroundColor
The background of the "Select Payment Method" bottom sheet header
UIColor
switchOnTintColor
The color of switch (toggle) control
UIColor
showPaymentDetails
Boolean variable determining whether the “Payment Details” section should be displayed or hidden.
Boolean
color
UIColor
font
UIFont
fontFamily
String
enabledTitleColor
UIColor
disabledTitleColor
UIColor
font
UIFont
enabledBackgroundColor
UIColor
disabledBackgroundColor
UIColor
fontFamily
String
left
Int
top
Int
right
Int
bottom
Int
To configure the theme, similar steps must be followed as described in the test app file.
Code Snippet:
func createTheme() - > CheckoutTheme {
var theme = CheckoutTheme()
theme.backgroundColor = .systemBackground
theme.backgroundColorModal = .secondarySystemBackground
theme.margins = UIEdgeInsets(top: 8, left: 2, bottom: 8, right: 2)
theme.mainTitle.color = .label
theme.mainTitle.fontFamily = "Arial"
theme.button.enabledTitleColor = .payButtonTitle
theme.button.disabledTitleColor = .payButtonDisabledTitle
theme.button.fontFamily = "Arial"
theme.button.enabledBackgroundColor = .payButtonBackground
theme.button.disabledBackgroundColor = .payButtonDisabledBackground
return theme
}The theme object is passed to the SDK initialization as shown below:
Code Snippet:
self.checkout = Checkout(
theme: theme,
sessionId: sessionId,
merchantId: merchantId,
apiKey: apiKey,
delegate: self
)The payment options display can be adjusted using the SDK with the following settings:
mode(BottomSheetorList)visibleItemsCount(default is 5)defaultSelectedPgCode(default is empty)
By default, BottomSheet mode is used, as set in previous releases. List mode is a new option, where a list of payment methods is displayed above the Payment Details section and the Pay button.
A view with a selected item
A view with an expanded list:
visibleItemsCountis an unsigned integer that sets how many payment options are shown at once. It only works in List mode. If there are fewer options than the number set, the list height will adjust to show only the available options.
defaultSelectedPgCodeis a payment gateway (PG) code that will be automatically selected. The SDK will look for the matching payment option and select it if found. If not found, no payment option will be selected.
All these parameters are optional and can be passed to Checkout.init through the following object:
displaySettings: PaymentOptionsDisplaySettings(
mode: paymentOptionsDisplayMode,
visibleItemsCount: visibleItemsCount,
defaultSelectedPgCode: defaultSelectedPgCode
)To view the full function call, please refer to the Ottu SDK - iOS | Example chapter in the documentation. This section provides the complete example, including how the function is used in the context of the Ottu SDK.
When the integration between Ottu and Apple for Apple Pay is completed, the necessary checks to display the Apple Pay button are handled automatically by the Checkout SDK.
Initialization: Upon initialization of the Checkout SDK with the provided session_id and payment gateway codes (pg_codes), several conditions are automatically verified:
It is confirmed that a
session_idandpg_codesassociated with the Apple Pay Payment Service have been supplied.It is ensured that the customer is using an Apple device that supports Apple Pay. If the device is not supported, the button will not be shown, and an error message stating
This device doesn't support Apple Paywill be displayed to inform the user of the compatibility issue.It is verified that the customer has a wallet configured on their Apple Pay device. if the wallet is not configured (i.e., no payment cards are added), the Setup button will appear. Clicking on this button will prompt the Apple Pay wallet on the user's device to open, allowing them to configure it by adding payment cards.
Displaying the Apple Pay Button: If all these conditions are met, the Apple Pay button is displayed and made available for use in the checkout flow.
Restricting Payment Options: To display only the Apple Pay button,
applePayshould be passed within theformsOfPaymentparameter. TheformsOfPaymentproperty instructs the Checkout SDK to render only the Apple Pay button. If this property is not included, all available payment options are rendered by the SDK.
This setup ensures a seamless integration and user experience, allowing customers to easily set up and use Apple Pay during the checkout process.
When the integration between Ottu and STC Pay is completed, the necessary checks to display the STC Pay button are handled seamlessly by the Checkout SDK.
Initialization: Upon initialization of the Checkout SDK with the provided session_id and payment gateway codes (pg_codes), several conditions are automatically verified:
It is confirmed that the
session_idandpg_codesprovided during SDK initialization are associated with the STC Pay Payment Service. This ensures that the STC Pay option is available for the customer to choose as a payment method.It is ensured that the STC Pay button is displayed by the iOS SDK, regardless of whether the customer has provided a mobile number while creating the transaction.
This setup ensures a seamless integration and user experience, allowing customers to easily set up and use STC Pay during the checkout process.
Due to compliance requirements, KNET necessitates a popup displaying the payment result after each failed payment. This functionality is available only in the cancelCallback when there is a response from the payment gateway. As a result, the user must click on the Apple Pay button again to retry the payment.
To properly handle the popup notification for KNET, the following code snippet should be implemented into your payment processing flow:
func cancelCallback(_ data: [String: Any] ? ) {
var message = ""
if let paymentGatewayInfo = data ? ["payment_gateway_info"] as ? [String: Any],
let pgName = paymentGatewayInfo["pg_name"] as ? String,
pgName == "kpay" {
message = paymentGatewayInfo["pg_response"].debugDescription
} else {
message = data?.debugDescription ?? ""
}
navigationController?.popViewController(animated: true)
let alert = UIAlertController(title: "Canсel", message: message, preferredStyle: .alert)
alert.addAction(UIAlertAction(title: "OK", style: .cancel))
self.present(alert, animated: true)
}
}The above code performs the following checks and actions:
Verification: It first checks if the cancel object contains information about the payment gateway
payment_gateway_info.Payment Gateway Identification: It then verifies if the
pg_nameproperty inpayment_gateway_infois equal to "kpay", confirming that the payment gateway used is KNET.Response Handling: If the conditions are met, it retrieves the payment gateway's response from the
pg_responseproperty. If not available, it uses a default "Payment was cancelled." error message.Popup Notification: Finally, it displays the error message in a popup using
self.present(alert, animated: true)to notify the user about the failed payment.
This setup ensures compliance with KNET's requirements and provides a clear user experience for handling failed payments.
This payment option enables direct payments through the mobile SDK. The SDK provides a user interface where the Cardholder Data (CHD) is entered by the user. If permitted by the backend, the card can be tokenized and saved for future payments.
Below is an example of how the onsite checkout screen appears:
The SDK supports multiple instances of onsite checkout payments. Therefore, for each payment method with a PG code of ottu_pg, the card form (as described above) will be displayed.
The SDK utilizes Sentry for error logging and reporting, which is initialized based on the configuration from SDK Studio. However, since the SDK is integrated into the merchant's app, conflicts may arise if the app also uses Sentry. To avoid this, merchants can disable Sentry in the Checkout SDK by setting the is_enabled flag to false in the configuration.
To enable the detection of jailbroken devices, the following section must be added to the application's Info.plist file:
<key > LSApplicationQueriesSchemes < /key>
<array >
<string > zbra < /string>
<string > cydia < /string>
<string > undecimus < /string>
<string > sileo < /string>
<string > filza < /string>
<string > activator < /string>
</array>
The SDK implements screen capture restrictions to prevent the collection of sensitive data. This applies to fields containing Cardholder Data (CHD), such as the onsite checkout form for entering card details and the CVV field for tokenized payments.
This technique works in two ways:
When attempting to take a screenshot of a protected screen, the fields appear empty, even if they contain input.
When attempting to record a video of the screen, the video is completely blurred, making the content unreadable.
The SDK supports the following payment forms: tokenPay, ottuPG, redirect applePay and stcPay. Merchants can display specific methods according to their needs.
For example, if you want to only show the STC Pay button, you can do so using formsOfPayment = [stcPay], and only the STC Pay button will be displayed. The same applies for applePay and other methods.
It is required to have a device running iOS 13 or higher.
Yes, see the Customization theme section.
The payment request for Apple Pay can be customized using its initialization methods. These methods allow the configuration of various properties, including:
API version
Supported card types
Accepted networks
Applicable countries
Merchant capabilities
For a complete list of supported properties, refer to the Apple Pay documentation.
Last updated