The smarter way
  • Getting Started
  • USER GUIDE
    • Payment Gateway
    • Currencies
    • Apple Pay
      • Setup MPGS
      • Setup Cybersource
    • Payment Tracking
      • Payment Transactions Insights
      • Payment Transactions States
      • Notifications, URLs & Timing
    • Plugins
      • Payment Request
      • E-Commerce
      • Bulk payment request
    • Features
      • Refund & Void Access Control
      • Two-Step Refund & Void Authorization
    • Integration
    • Configuration
      • Global Configuration
      • Webhooks Configuration
      • Transaction Report Configuration
      • How to Get API Keys
      • URL Shortener Configuration
    • Notification Communication Channels
      • Email Notifications
      • SMS Notifications
      • WhatsApp Notifications
        • Integrated WhatsApp Channel
        • Manual WhatsApp Channel
      • Notification Templates
      • Notification Process: Automatic and Manual
    • Satellite
    • Real Estate
      • Regular Activities
        • Property management
        • Tenant and Contract Management
          • Tenant & Contract Dashboard
          • Tenant Management
          • Contract Management
            • Add New Contract
            • Contract Action
              • Renew Contract
              • Terminate Contract
              • Manual Payment
              • Suspend Contract
              • Resume Contract
              • Advance Payment
        • Generate Invoice
        • Invoices Management
        • Maintenance
        • Transactions
        • Auditing and Rolling Back Activities
      • Merchant First Journey
  • developer
    • Getting Started
    • Tokenization
    • Authentication
    • Payment Methods
    • Checkout API
    • Operations
    • User Cards
    • Payment Status-Inquiry
    • Auto-Debit
    • Invoice API
    • Message Notifications
    • Upload Attachment
    • Checkout SDK
      • Web
      • iOS
      • Android
      • Flutter
    • Webhooks
      • Payment Notification
      • Operation Notification
      • Signing Mechanism
      • Integration Guides
        • Laravel Webhook Receiver Guide
        • .NET Webhook Receiver Guide
    • Test Cards
Powered by GitBook
On this page
  • Installation
  • Minimum Requirements
  • Installation with dependency
  • Native UI
  • SDK Configuration
  • Language
  • Light and dark theme
  • Functions
  • Checkout.init
  • Properties
  • Callbacks
  • errorCallback
  • cancelCallback
  • successCallback
  • Example
  • Customization Theme
  • Properties description
  • Data types description
  • Example
  • STC Pay
  • Onsite Checkout
  • Error Reporting
  • Cyber Security Measures
  • Rooting Detection
  • FAQ
  1. developer
  2. Checkout SDK

Android

PreviousiOSNextFlutter

Last updated 1 month ago

The from Ottu is a Kotlin-based library designed to streamline the integration of an Ottu-powered into Android applications. This SDK allows for complete customization of the checkout experience, including both appearance and functionality, as well as the selection of accepted payment methods.

To integrate the Checkout SDK, it must be incorporated into the Android application and initialized with the following parameters:

Additionally, various configuration options, such as accepted and styling for the checkout interface, can be specified to enhance the user experience.

The should never be utilized on the client side; instead, use the . This is essential for maintaining the security of your application and safeguarding sensitive data.

The SDK is compatible with devices running Android 8 or higher (API version 26 or later).

allprojects {
    repositories {
        // Other repositories...
        maven { url "https://jitpack.io" }
    }
}

dependencies {
    implementation 'com.github.ottuco:ottu-android-private:2.0.0'
}

The SDK UI is embedded as a Fragment within any part of an Activity in the merchant's application.

Example:

If a wallet is the only available payment option, the UI is minimized automatically.

The SDK supports two languages, English and Arabic, with English set as the default.

The SDK supports UI customization to match the device theme—light or dark. This adjustment is applied during the SDK initialization, based on the device's settings. Similarly, for language, no adjustments are made within the app.

The function initiates the checkout process and configures the required settings for the Checkout SDK. It should be invoked once by the parent app to start the checkout sequence, called with set of configuration fields that encapsulate all essential options for the process.

When you call Checkout.init, the SDK manages the setup of key components for the checkout, like generating a form for customers to input their payment information, and facilitating the communication with Ottu's servers to process the payment.

This function returns a Fragment object, which is a native Android UI component that can be integrated into any part of an Activity instance (also native to Android).

The merchant_id identifies your Ottu merchant domain. It should be the root domain of your Ottu account, excluding the "https://" or "http://" prefix.

For instance, if your Ottu URL is https://example.ottu.com, then your merchant_id would be example.ottu.com. This attribute is utilized to determine which Ottu merchant account to associate with the checkout process.

The session_id serves as the unique identifier for the payment transaction linked to the checkout process.

Available Options for formsOfPayment

  • cardOnsite: A direct payment method (onsite checkout) where cardholder data (CHD) is entered directly in the SDK. If 3DS authentication is required, a payment provider is involved.

  • stcPay: Requires customers to enter their mobile number and authenticate with an OTP sent to their device to complete the payment.

  • flexMethods: Allows payments to be split into multiple installments. These methods, also known as BNPL (Buy Now, Pay Later), support providers such as Tabby and Tamara.

The ApiTransactionDetails class object stores transaction details.

If this object is provided, the SDK will not need to retrieve transaction details from the backend, thereby reducing processing time and improving efficiency.

The theme class object is used for UI customization, allowing modifications to background colors, text colors, and fonts for various components.

In the Checkout SDK, callback functions are essential for delivering real-time updates on the status of payment transactions. These callbacks improve the user experience by facilitating smooth and effective management of different payment scenarios, including errors, successful transactions, and cancellations.

The callbacks outlined below are applicable to any type of payment.

The errorCallback is a callback function triggered when issues occur during a payment process. Properly handling these errors is essential for maintaining a smooth user experience.

To set up the errorCallback function, use the data-error attribute on the Checkout script tag to designate a global function that will manage errors. If an error arises during a payment, the errorCallback function will be called, receiving a JSONObject with a data.status value indicating an 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 is a callback function in the Checkout SDK that is activated when a payment is canceled.

To configure 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 payment is canceled by a customer, the cancelCallback function will be called, and it will receive a JSONObject containing 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.

The successCallback is a function that is triggered when the payment process is successfully completed. This callback receives a JSONObject containing a data.status value of "success."

Params Available in data JSONObject for successCallback

  • message mandatory

  • form_of_payment mandatory

  • 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 assigned by setting the data-success attribute on the Checkout script tag. This attribute specifies a global function that will be invoked when the payment process successfully completes.

val theme = getCheckoutTheme()

// Builder class is used to construct an object passed to the SDK initializing function
val builder = Checkout
    .Builder(merchantId!!, sessionId, apiKey!!, amount!!)
    .formsOfPayments(formsOfPayment)
    .theme(theme)
    .logger(Checkout.Logger.INFO)
    .build()

// Actual `init` function calling, returning a `Fragment` object  
checkoutFragment = Checkout.init(
    context = this @CheckoutSampleActivity,
    builder = builder,
    setupPreload = setupPreload,
    successCallback = {
        Log.e("TAG", "successCallback: $it")
        showResultDialog(it)
    },
    cancelCallback = {
        Log.e("TAG", "cancelCallback: $it")
        showResultDialog(it)
    },
    errorCallback = {
        errorData,
        throwable - >
        Log.e("TAG", "errorCallback: $errorData")
        showResultDialog(errorData, throwable)
    },
)

The class responsible for defining the theme is called CheckoutTheme.

Customization Theme Class Structure:

class CheckoutTheme(
    val uiMode: UiMode = UiMode.AUTO,
    val appearanceLight: Appearance ? = null,
    val appearanceDark : Appearance ? = null,
    val showPaymentDetails : Boolean = true,
)

Specifies the device theme mode, which can be set to:

  • light

  • dark

  • auto (automatically adjusts based on system settings)

These are optional instances of the Appearance class, which enable UI customization for light mode and dark mode, respectively.

The Appearance class serves as the core inner class of CheckoutTheme, containing objects that define various UI components.

A boolean field that determines whether the "Payment Details" section should be displayed or hidden.

All properties are optional and can be customized by the user.

General

Property Name
Description
Data Type

mainTitleText

Font and color for all “Captions”

titleText

Font and color for payment options in the list

subtitleText

Font and color for payment options details (like expiration date)

Fees

Property Name
Description
Data Type

feesTitleText

Font and color of fees value in the payment options list

feesSubtitleText

Font and color of fees description in the payment options list

Data

Property Name
Description
Data Type

dataLabelText

Font and color of payment details fields (like “Amount”)

dataValueText

Font and color of payment details values

Other

Property Name
Description
Data Type

errorMessageText

Font and color of error message text in pop-ups

Property Name
Description
Data Type

inputTextField

Font and color of text in any input field (including disabled state)

Property Name
Description
Data Type

sdkbackgroundColor

The main background of the SDK view component

modalBackgroundColor

The background of any modal window

paymentItemBackgroundColor

The background of an item in payment options list

selectorIconColor

The color of the icon of the payment

savePhoneNumberIconColor

The color of “Diskette” button for saving phone number

Property Name
Description
Data Type

button

Background, text color and font for any button

backButton

Color of the “Back” navigation button

selectorButton

Background, text color and font for payment item selection button

Property Name
Description
Data Type

switch

Colors of the switch background and its toggle in different states (on, off and disabled)

Property Name
Description
Data Type

margins

Top, left, bottom and right margins between component

Property Name
Description
Data Type

color

Main color integer value

Int

colorDisabled

Disabled stated color integer value

Int

Property Name
Description
Data Type

color

Main color integer value

Int

rippleColor

Ripple color integer value

Int

colorDisaled

Disabled stated color integer value

Int

Property Name
Description
Data Type

textColor

Main color integer value

fontType

Font resource ID

Int

Property Name
Description
Data Type

background

Background color integer value

primaryColor

Text color

focusedColor

Selected text color

text

Text value

error

Text value

Property Name
Description
Data Type

rippleColor

Button background color

fontType

Button text font ID

Int

textColor

Button text color

Property Name
Description
Data Type

checkedThumbTintColor

Toggle color in checked state

Int

uncheckedThumbTintColor

Toggle color in unchecked state

Int

checkedTrackTintColor

Track color in checked state

Int

uncheckedTrackTintColor

Track color in unchecked state

Int

checkedTrackDecorationColor

Decoration color in checked state

Int

uncheckedTrackDecorationColor

Decoration color in unchecked state

Int

Property Name
Data Type

left

Int

top

Int

right

Int

bottom

Int

To build the theme, the user must follow steps similar to those outlined in the test app file.

Code Snippet:

val appearanceLight = CheckoutTheme.Appearance(
    mainTitleText = CheckoutTheme.Text(
        textColor = CheckoutTheme.Color(Color.WHITE),
        R.font.roboto_bold
    ),
    titleText = CheckoutTheme.Text(textColor = CheckoutTheme.Color(Color.BLACK)),
    subtitleText = CheckoutTheme.Text(textColor = CheckoutTheme.Color(Color.BLACK)),

    button = CheckoutTheme.Button(
        rippleColor = CheckoutTheme.RippleColor(
            color = Color.WHITE,
            rippleColor = Color.BLACK,
            colorDisabled = Color.GRAY
        ),
        textColor = CheckoutTheme.Color(color = Color.BLACK),
        fontType = R.font.roboto_bold
    ),

    margins = Margins(left = 12, top = 4, right = 12, bottom = 4),

    sdkBackgroundColor = CheckoutTheme.Color(color = Color.WHITE)
)

return CheckoutTheme(
    uiMode = CheckoutTheme.UiMode.AUTO,
    showPaymentDetails = showPaymentDetails,
    appearanceLight = appearanceLight,
    appearanceDark = appearanceDark,
)

Once the STC Pay integration between Ottu and STC Pay has been completed, the necessary checks are automatically handled by the Checkout SDK to ensure the seamless display of the STC Pay button.

  • The session_id and pg_codes provided during SDK initialization must be linked to the STC Pay Payment Service. This verification ensures that the STC Pay option is made available for selection as a payment method.

Regardless of whether a mobile number has been entered by the customer during transaction creation, the STC Pay button is displayed by the Android SDK.

This payment option facilitates direct payments within the mobile SDK. A user-friendly interface allows users to securely input their CHD. If permitted by the backend, the card can be stored as a tokenized payment for future transactions.

Example:

The SDK utilizes Sentry for error logging and reporting, with initialization based on the configuration provided by SDK Studio.

Since the SDK is embedded within the merchant's application, conflicts may arise if Sentry is also integrated into the app. To prevent such conflicts, Sentry can be disabled within the Checkout SDK by setting the is_enabled flag to false in the configuration.

The SDK prevents execution on rooted devices.

To enforce this restriction, rooting checks are performed during SDK initialization. If a device is detected as rooted, a modal alert dialog is displayed, providing an explanation. The message shown is as follows:

This device is not secure for payments. Transactions are blocked for security reasons.

After dismissing the alert, the app crashes unexpectedly

Checkout.init function needs to be called in a coroutine.

The SDK accommodates various payment forms includingtokenPay, redirect, stcPay and cardOnsite.

Merchants have the flexibility to showcase specific methods based on their requirements.

For instance, if you wish to exclusively display the STC Pay button, you can achieve this by setting formsOfPayment = [stcPay], which will result in only the STC Pay button being displayed. This approach is applicable to other payment methods as well.

It is required to have a device running Android 8 or higher (Android API level 26 or higher).

It automatically adopts the language configured in the device settings, requiring no in-app adjustments. However, if a transaction is initiated in a different language and setup preload is utilized, the backend-generated text (such as fee descriptions) will appear in the language of the transaction. Therefore, it is important to ensure that the language code passed to the 's transaction creation request matches the currently selected language on the device or current selected app language.

Currently, the SDK offers a single that serves as the entry point for the merchant's application. It also includes that must be managed by the parent app, which are detailed in the following .

string required

string required

The apiKey is your Ottu , which is essential for authenticating communications with Ottu's servers during the checkout process.

Make sure to use the public key and avoid using the private key. The must be kept confidential at all times and should never be shared with any clients.

string required

This identifier is automatically generated at the creation of the payment transaction. For additional details on how to utilize the session_id parameter in the I, refer to the section.

array optional

The formsOfPayment parameter allows customization of the payment methods displayed in the . By default, all forms of payment are enabled.

tokenPay: Uses to securely store and process customers' payment information.

redirect: Redirects customers to an external or a third-party payment processor to complete the transaction.

object optional

object optional

All fields in the theme class are optional. If a theme is not specified, the default UI settings will be applied. For more details, refer to the section.

Uint required

Callback functions are used to retrieve the payment status and must be provided directly to the Checkout initialization function. For more details, refer to the section.

The best practice recommended in the event of an error is to restart the checkout process by generating a new session_id through the .

The component names within Appearance largely correspond to those described .

If a property is not specified, the default value (as defined in the Figma design ) will be automatically applied.

Upon initialization of the Checkout SDK with the and payment gateway codes (), the following condition is automatically verified:

Yes, check the section.

Checkout API
Checkout.init
tokenization
Checkout API
here
Native UI
SDK Configuration
Language
Light and dark theme
Functions
function
callbacks
section
Properties
merchantId
apiKey
sessionId
formsOfPayment
setupPreload
theme
Customization Theme
successCallback, errorCallback and successCallback
Callbacks
Callbacks
errorCallback
cancelCallback
successCallback
Example
Customization Theme
uiMode
appearanceLight & appearanceDark
here
showPaymentDetails
Properties description
Texts
Text Fields
Colors
Buttons
Switch
Margins
Data types description
Color
RippleColor
Text
TextField
Button
Switch
Margins
Example
STC Pay
Onsite Checkout
Error Reporting
Cyber Security Measures
Rooting Detection
FAQ
1️
What forms of payments are supported by the SDK?
2️
What are the minimum system requirements for the SDK integration?
3️
Can I customize the appearance beyond the provided themes?
Customization Theme
Text
Text
Text
Text
Text
Text
Text
Text
TextField
Color
Color
Color
Color
Color
Button
RippleColor
Button
Switch
Margins
Color
Color
Color
Color
Text
Text
RippleColor
Color
Checkout SDK
payment methods
theme
Installation
Minimum Requirements
Installation with dependency
Checkout AP
checkout process
payment gateway
API public key
API private key
session_id
session_id
pg_codes
checkout process
API public key
API private key
API public key
session_id
merchant_id