iOS
Last updated
Last updated
The Checkout SDK is a Swift framework (library) provided by Ottu that allows you to easily integrate an Ottu-powered checkout process into your iOS application. With the Checkout SDK, you can customize the look and feel of your checkout process, as well as which forms of payment are accepted.
To use the Checkout SDK, you'll need to include the library in your iOS application and initialize it with your Ottu merchant_id, session_id, and API public key. You can also specify additional options such as, which forms of payment to accept, the theme styling for the checkout interface, and more.
API private key should never be used on the client side. Instead, API public key should be used. This is essential to ensure the security of your application and the protection of sensitive data.
The SDK can be used on a device running iOS 13 or higher.
Ottu: Ottu is available through CocoaPods. To install it, simply add the following line to your Podfile:
After all the frameworks are obtained via CocoaPods, it is needed to open project *.xcworkspace (not *.xcodeproj) in Xcode and ensure Minimum Deployments iOS is set to 13 for SVGKit as shown in the below figure:
The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.
Once you have your Swift package set up, adding Alamofire as a dependency is as easy as adding it to the dependencies value of your Package.swift.
Due to a current issue with the Swift Package Manager (Swift PM), if you choose to use Swift PM for installation, it is necessary to manually install the sentry-cocoa package in addition to the ottu_checkout_sdk.
The SDK UI is a View embedded in any part of any ViewController of the merchant's app.
Here is the example:
However, if there’s only one payment option available and it is a wallet, the UI is minified:
The SDK supports two languages: English and Arabic, the default one is English.
The SDK uses the language applied in the device settings. Nothing should be adjusted inside the app. However, if the transaction has been created with another language and setup preload is being used, the texts coming from the backend (like fees descriptions) will be in the transaction language. So please consider the current selected device language or current selected app language when passing a language code to the transaction creation request of Checkout API.
Also SDK supports UI adjustment according to the device theme - light or dark. It is applied when the SDK is been initialized, based on the device settings. Same as for the language - nothing is adjusted inside the app.
Currently the SDK provides only one function which is the entry point for the merchants app. Also it provides callbacks which should be handled by the parent app. They are described in the next chapter.
Is the function that initializes the checkout process and sets up the necessary configuration options for the Checkout SDK. It needs to be called once by the parent app to initialize the checkout process, and it must be called with a set of configuration fields that includes all the necessary options for the checkout process.
When you call Checkout.init, the SDK will take care of setting up the necessary components for the checkout process, such as creating a form for the customer to enter their payment details, and handling communication with Ottu's servers to process the payment.
This function returns a Viewobject. It is iOS native UI component which can be placed in any place of any ViewControllerinstance (also iOS native).
The merchant_id specifies your Ottu merchant domain. This should be the root domain of your Ottu account, without the "https://" or "http://" prefix.
For example, if your Ottu URL is https://example.ottu.com, then your merchant_id is example.ottu.com. This property is used to identify which Ottu merchant account the checkout process should be linked to.
The apiKey is your Ottu API public key. This key is used for authentication purposes when communicating with Ottu's servers during the checkout process.
According to the REST API documentation, the apiKey property should be set to your Ottu API public key.
Ensure that you utilize the public key and refrain from using the private key. The private key should remain confidential at all times and must not be shared with any clients.
The session_id is the unique identifier for the payment transaction associated with the checkout process.
This unique identifier is automatically generated when the payment transaction is created. For more information on how to use the session_id parameter in the Checkout API, see session_id.
formsOfPayment allows you to customize which forms of payment will be displayed in your checkout process. By default, all forms of payment are configured.
The available options for formsOfPayment are:
applePay: The Apple Pay payment method that allows customers to make purchases using their Apple Pay-enabled devices.
stcPay: A method where customers enter their mobile number and provide an OTP send to their mobile number to complete their payment.
ottuPG: A method that redirects customers to a page where customers enter their credit or debit card details to make a payment.
tokenPay: A payment method that uses tokenization to securely store and process customers' payment information.
redirect: A method where customers are redirected to a payment gateway or a third-party payment processor to complete their payment.
ApiTransactionDetails struct object containing the transaction details. If provided, the SDK will not require the transaction details from the backend, in order to save time.
Theme struct object for UI customization. All the fields are optional. Can contain values for background colors, text colors, fonts for various components. Allows customization for both light and dark device mode. See Customization Theme section for details.
Please note that theme is optional. If not provided, the default UI settings will be used.
An object providing the SDK callbacks to the app This is usually the parent app’s class corresponding to OttuDelegate aggregating the SDK object. In order the class to correspond to this delegate, it needs to implement 3 callback functions, please refer to Callbacks section for more information.
In the Checkout SDK, callback functions play a vital role in providing real-time updates on the status of payment transactions. Callbacks enhance the user experience by enabling seamless and efficient handling of various payment scenarios, such as errors, successful payments, and cancellations.
All the callbacks described below can be called for any type of payment.
The errorCallback is a callback function that is invoked when issues arise during a payment. It is important to handle errors appropriately to ensure a smooth user experience.
The recommended best practice in case of an error is to restart the checkout process by creating a new session_id using the Checkout API.
To define the errorCallback function, you can use the data-error attribute on the Checkout script tag to specify a global function that will handle errors. If an error occurs during a payment, the errorCallback function will be invoked with data JSONObject with a data.status value of error
Params Available in data JSONObject for errorCallback
message mandatory
form_of_payment mandatory
status mandatory
challenge_occurred optional
session_id optional
order_no optional
reference_number optional
The cancelCallback in the Checkout SDK is a callback function that is invoked when a payment is canceled.
To define the cancelCallback function, you can use the data-cancel attribute on the Checkout script tag to specify a global function that will handle cancellations. If a customer cancels a payment, the cancelCallback function will be invoked with data JSONObject with a data.status value of canceled.
Params Available in data JSONObject for cancelCallback
message mandatory
form_of_payment mandatory
challenge_occurred optional
session_id optional
status mandatory
order_no optional
reference_number optional
payment_gateway_info optional
In both cancelCallback and errorCallback, the SDK must be reinitialized, either on the same session or on a new session.
In the Checkout SDK, the successCallback is a function triggered upon successful completion of the payment process. This callback receives data JSONObject, with a data.status value of success
Params Available in data JSONObject for successCallback
message mandatory
form_of_paymentmandatory
challenge_occurred optional
session_id optional
status mandatory
order_no optional
reference_number optional
redirect_url optional
payment_gateway_info optional
The successCallback function is defined and passed as the value of the data-success attribute on the Checkout script tag.
The main class describing theme is called CheckoutTheme.
It uses additional component classes like:
ButtonComponent
LabelComponent
TextFieldComponent
The CheckoutTheme class includes objects that represent various UI components. These components' names largely align with those outlined below, however they also include additional fields specific to each platform.
Important Note: All the properties are optional. The user can customize any of them. If some property is not set the default value (specified in Figma design) will be used.
mainTitle
Font and color for all “Captions”
title
Font and color for payment options in the list
subtitle
Font and color for payment options details (like expiration date)
feesTitle
Font and color of fees value in the payment options list
feesSubtitle
Font and color of fees description in the payment options list
dataLabel
Font and color of payment details fields (like “Amount”)
dataValue
Font and color of payment details values
Other
errorMessageText
Font and color of error message text in pop-ups
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
button
Background, text color and font for any button
selectorButton
Background, text color and font for payment item selection button
switchOnTintColor
The color of switch (toggle) control
UIColor
margins
Top, left, bottom and right margins between compone
showPaymentDetails
Boolean variable determining whether the “Payment Details” section should be displayed or hidden.
Boolean
color
UIColor
font
UIFont
fontFamily
String
label
text
backgroundColor
UIColor
enabledTitleColor
UIColor
disabledTitleColor
UIColor
font
UIFont
enabledBackgroundColor
UIColor
disabledBackgroundColor
UIColor
fontFamily
String
left
Int
top
Int
right
Int
bottom
Int
In order to build the theme the user needs to perform similar actions described in this file of the test app.
Here is a code snippet:
And here is how it is been passed to the SDK initiazliation (theme object):
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_id and pg_codes associated 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 Pay will 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, applePay should be passed within the formsOfPayment parameter. The formsOfPayment property 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_id and pg_codes provided 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.
The popup notification requirement is specific to the KNET payment gateway. Other payment gateways may have different requirements or notification mechanisms, so it is essential to follow the respective documentation for each payment gateway integration.
To properly handle the popup notification for KNET, the following code snippet should be implemented into your payment processing flow:
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_name property in payment_gateway_info is 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_response property. 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.
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.
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.
You can tailor the payment request for Apple Pay using their respective initialization methods. These methods allow you to set various properties like API version, supported cards, networks, countries, and merchant capabilities etc. You can check the list of properties supported by ApplePay
