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:

pod 'Ottu', :git => 'https://github.com/ottuco/ottu-ios.git', :tag => '1.0.14'

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.

dependencies: [
    .package(url: "https://github.com/ottuco/ottu-ios.git")
]

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).

merchantId string required

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.

apiKey string required

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.

sessionId string required

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 array optional

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.

setupPreload object optional

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 object optional

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.

delegate object required

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 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.

self.checkout = Checkout(
    formsOfPayments: formsOfPayment,
    sessionId: sessionId,
    merchantId: merchantId,
    apiKey: apiKey,
    delegate: self
)
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:

  • 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:

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
}

And here is how it is been passed to the SDK initiazliation (theme object):

self.checkout = Checkout(
    theme: theme,
    sessionId: sessionId,
    merchantId: merchantId,
    apiKey: apiKey,
    delegate: self
)

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.

  1. 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.

  2. 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.

  3. 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.

  1. 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:

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:

  1. Verification: It first checks if the cancel object contains information about the payment gateway (payment_gateway_info).

  2. 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.

  3. 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.

  4. 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