iOS
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:
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
.
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 View
object. It is iOS native UI component which can be placed in any place of any ViewController
instance (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
mandatoryform_of_payment
mandatorystatus
mandatorychallenge_occurred
optionalsession_id
optionalorder_no
optionalreference_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
JSONObjec
t with a data.status value of canceled
.
Params Available in data
JSONObject
for cancelCallback
message
mandatoryform_of_payment
mandatorychallenge_occurred
optionalsession_id
optionalstatus
mandatoryorder_no
optionalreference_number
optionalpayment_gateway_info
optional
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
mandatoryform_of_payment
mandatorychallenge_occurred
optionalsession_id
optionalstatus
mandatoryorder_no
optionalreference_number
optionalredirect_url
optionalpayment_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.
General
Fees
Data
Other
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
andpg_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 theformsOfPayment
parameter. TheformsOfPayment
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
andpg_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 inpayment_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
Last updated