Android
The Checkout SDK from Ottu is a Kotlin-based library designed to simplify the integration of an Ottu-powered checkout process into your Android app. This SDK enables you to tailor the appearance and functionality of your checkout process, including the selection of accepted payment methods.
The Checkout SDK must be incorporated into your Android application, and it must be initialized using your Ottu merchant_id, session_id, and API public key. Various settings, such as the accepted payment methods and the theme styling for the checkout interface, may also be specified.
The API private key should never be utilized on the client side; instead, use the API public key. This is essential for maintaining the security of your application and safeguarding sensitive data.
The SDK can be used on a device running Android 8 or higher (API version 26 or higher).
The SDK UI is a Fragment
embedded in any part of any Activity
of the merchant's app.
Here is the example:
However, if there’s only one payment option available and it it a wallet, the UI is minified:
The SDK supports two languages, English and Arabic, with English set as the default.
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 Checkout API's transaction creation request matches the currently selected language on the device or current selected app language.
The SDK also 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.
Currently, the SDK offers a single function that serves as the entry point for the merchant's app. It also includes callbacks that must be managed by the parent app, which are detailed in the following chapter.
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 apiKey
is your Ottu API public key, which is essential for authenticating communications with Ottu's servers during the checkout process. As outlined in the REST API documentation, the apiKey
property should be assigned your Ottu API public key.
Make sure to use the public key and avoid using the private key. The API private key must be kept confidential at all times and should never be shared with any clients.
The session_id
serves as the unique identifier for the payment transaction linked to the checkout process.
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 Checkout API, refer to the session_id section.
The formsOfPayment
allows you to select which payment methods will appear during your checkout process. By default, all available payment options are enabled.
The options for formsOfPayment
include:
ottuPG
: This method redirects customers to a page where they can enter their credit or debit card details to make a payment.tokenPay
: This payment method utilizes tokenization to securely store and process customers' payment details.redirect
: This method redirects customers to a payment gateway or a third-party payment processor for payment completion.stcPay
: In this method, customers use their mobile number and confirm the transaction with an OTP sent to their mobile to finalize their payment.
The ApiTransactionDetails
class object contains the transaction details. If this object is provided, the SDK will not need to retrieve the transaction details from the backend, thereby saving time.
Theme
class object for UI customization. All the fields are optional. Can contain values for background colors, text colors, fonts for various components.. See Customization Theme section for more details.
Please note that theme
is optional. If not provided, the default UI settings will be used.
The callback functions used for getting payment status. They should be provided directly to the Checkout initialization function. See Callacks for more information.
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.
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.
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.
The best practice recommended in the event of an error is to restart the checkout process by generating a new session_id
through the Checkout API.
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
mandatoryform_of_payment
mandatorystatus
mandatorychallenge_occurred
optionalsession_id
optionalorder_no
optionalreference_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
mandatoryform_of_payment
mandatorychallenge_occurred
optionalsession_id
optionalstatus
mandatoryorder_no
optionalreference_number
optionalpayment_gateway_info
optional
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
mandatoryform_of_payment
mandatorychallenge_occurred
optionalsession_id
optionalstatus
mandatoryorder_no
optionalreference_number
optionalredirect_url
optionalpayment_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.
The class describing theme is called CheckoutTheme
.
Here’s how the customization theme class looks like:
Determines device theme: light, dark or auto.
These are optional instances of Appearance
class (see description below). They allow UI customization for device light and dark mode respectively.
Appearance
class is the main inner class of CheckoutTheme
. It contains objects describing different UI components. The names of the components mostly correspond to described in this document:
Is a boolean field determining whether “Payment details” section should be displayed or hidden.
Important Note:All properties are optional and customizable by the user. If a property is not specified, the default value, as outlined in the above Figma design, will be used.
General
Fees
Data
Other
To construct the theme, the user needs to carry out actions similar to those detailed in this test app file.
Below is the code snippet:
Once the STC Pay integration between Ottu and STC Pay has been completed, the Checkout SDK will automatically handle the necessary checks to seamlessly display the STC Pay button. Upon initialization of the Checkout SDK with your session_id
and payment gateway codes (pg_codes
), the following conditions are verified automatically:
The session_id
and pg_codes
supplied during SDK initialization must be linked to the STC Pay Payment Service. This verification ensures that the STC Pay option is available for the customer to select as a payment method.
Regardless of whether a mobile number has been provided by the customer during transaction creation, the STC Pay button is displayed by the Android SDK.
The SDK uses Sentry
for error logging and reporting. It is initialized based on the config coming from SDK Studio. However, since the SDK is a framework been embedded to the merchant app it can cause conflicts in case the app also uses Sentry. So the merchant can disable Sentry in the Checkout SDK by setting is_enabled
flag to false
in the config.
The SDK accommodates various payment forms including tokenPay, ottuPG, redirect, and stcPay. 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).
Yes, check the Customization theme section.
Last updated