Web
Last updated
Last updated
In this documentation, you will find comprehensive resources and guides to help you seamlessly integrate and leverage the features of SDK Version 3 in your development projects. Whether you're an experienced developer or just starting out, this documentation is designed to assist you at every step. For SDK Version 2 Documentation, please visit the following link: SDK Version 2 Documentation
The Checkout SDK is a JavaScript library provided by Ottu that allows you to easily integrate an Ottu-powered checkout process into your web 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 web application and initialize it with your Ottu merchant_id, session_id, and API key. You can also specify additional options such as, which forms of payment to accept, the theme styling for the checkout interface, and more.
Please note that the Checkout SDK requires the implementation of the Checkout API in order to function properly.
For optimal security, call REST APIs from server-side implementations, not client-side applications such as mobile apps or web browsers.
Below is a demo of the Checkout SDK in action. This demo shows how the Checkout SDK can be used to create a streamlined checkout experience for customers, with support for multiple forms of payment and a customizable interface.
To install the Checkout SDK, you'll need to include the library in your web application by adding a script tag to your HTML section. You can do this by using the following code snippet:
Replace errorCallback, cancelCallback, successCallback, and beforePayment with the names of your error handling, cancel handling, success handling, and beforePayment handling functions, respectively.
You're all set! You can now use the Checkout SDK to create a checkout form on your web page and process payments through Ottu.
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 on your web page to initialize the checkout process, and it must be called with a configuration object 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.
The Checkout.reload
function in the Checkout SDK is used to refresh the SDK. It's useful when you want to reload the content of the SDK after an error has occurred or when the content needs to be refreshed.
Here's an example of how Checkout.reload
might be called:
string
The selector
property in the Checkout SDK is used to specify the css
selector for the HTML element that will contain the checkout form. This is typically a <div>
element on your web page.
To specify the selector, you can add a <div>
element to your web page with a unique id
attribute, like this:
It's important to note that the selector
property must be the ID of the HTML element that will contain the checkout form. This is because the Checkout SDK replaces the contents of the specified element with the checkout elements.
Here's an example of how Checkout.init
might be called with a selector
property:
string
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.
string
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.
string
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.
string
The lang
property serves to designate the language for presenting the checkout elements. You can configure this property with either en
for English or ar
for Arabic. When lang
is configured as en
, the checkout form will appear in English, and if set to ar
, the checkout elements will be shown in Arabic. Moreover, when the lang
parameter is set to ar
, the layout will adapt to a right-to-left (RTL) orientation to suit Arabic script.
For seamless user experience, it's recommended to maintain consistency by passing the same value for lang
in Checkout.init used in Checkout API while creating transactions.
For more information on how to use lang parameter in the Checkout API, please refer to language parameter in Checkout API
section.
array
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.
googlePay
: The Google Pay payment method that allows customers to make purchases using their Google wallet cards linked in google accounts.
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.
stcPay
: A method where customers enter their mobile number and provide an OTP send to their mobile number to complete their payment.
urPay
: A method where customers enter their mobile number and provide an OTP send to their mobile number to complete their payment.
string
There are two display Modes i.e grid
& column
.The Default displayMode
is column
. Here's an example of how Checkout.init
might be called to customize the displayMode
object
The setupPreload
feature is designed to optimize the SDK
loading experience by allowing merchants to pre-fetch transaction details and pass them to the SDK
during initialization. This eliminates the need for the SDK
to make an API call, resulting in faster rendering of the UI.
To utilize the setupPreload
feature, include it as a property when calling checkout.init(). The setupPreload
object should contain the prefetched transaction details.
The setupPreload
functionality relies heavily on the Checkout API. When calling the create or update operation of a payment transaction (using the session_id), set the include_sdk_setup_preload flag to true
. This action will prompt the API to return the sdk_setup_preload_payload
key, along with other values. Pass this value into the Checkout.init()
just as you pass the session_id
, ensuring no modifications are made to it.
For more information on how to use the setupPreload
parameter, see sdk_setup_preload_payload in the Checkout API.
If the setupPreload
object passed during SDK
initialization is not valid or does not adhere to the required structure, the SDK
will discard it and automatically fall back to its previous functionality. In such cases, the SDK
will initiate an API call to fetch the necessary transaction details from the backend. It is essential to ensure that the setupPreload
object follows the specified format to leverage the instant loading feature effectively and avoid fallback scenarios and ensure a seamless integration.
object
The applePayInit
object enables users to modify the Apple Pay configurations used for generating payment sessions through Apple Pay. By default, all options are pre-configured. However users have the flexibility to customize these configurations using applePayInit
according to their requirements.
buttonLocale
Users can change Apple Pay Button Locale by using buttonLocale property.
Value of buttonLocale must be a 2 letter language code like ar
, en
etc.
version Users can change the API version used for creating Apple Pay payment session by using the version property. Values supported by version are written here.
In addition to above properties, users have the capability to customize the Apple Pay payment request using properties defined here. However, due to backend constraints, not all properties are modifiable. Below is the list of supported and unsupported values:
merchantCapabilities
merchantIdentifier
supportedNetworks
countryCode
supportedCountries
total
lineItems
currencyCode
requiredBillingContactFields
billingContact
requiredShippingContactFields
shippingContact
shippingContactEditingMode
supportsCouponCode
couponCode
applicationData
object
The googlePayInit
object enables users to modify the Google Pay configurations used for generating payment sessions through Google Pay. By default, all options are pre-configured. However, developers have the flexibility to customize these configurations using googlePayInit
according to their requirements.
buttonLocale
Users can change Google Pay Button Locale by using buttonLocale
property.
Value of buttonLocale
must be a 2 letter language code like ar
, en,
etc...
In addition to above properties, users have the capability to customize Google Pay payment request by utilizing the options outlined in the documentation here.However, due to backend constraints, not all properties are modifiable. Below is the list of supported and unsupported values:
apiVersion
apiVersionMinor
environment
emailRequired
merchantId
merchantName
tokenizationSpecificationType
publicKey
gateway
gatewayMerchantId
allowedAuthMethods
allowedCardNetworks
allowPrepaidCards
allowCreditCards
billingAddressRequired
assuranceDetailsRequired
billingAddressParameters
displayItems
totalPrice
totalPriceLabel
totalPriceStatus
countryCode
currencyCode
shippingAddressRequired
shippingAddressParameters
shippingOptionRequired
shippingOptionParameters
offerInfo
callbackIntents
existingPaymentMethodRequired
Example
object
The SDK Theme Customization feature allows you to modify the appearance of elements within the SDK using a theme
object. This object contains specific css
properties that are applied to various components, giving you control over their styling. theme
object consists of key-value pairs, where each key corresponds to a specific component, and the associated value is a set of css
properties to be applied to that component
Hide Amount
Using the theme
object merchant can hide the amount and payment details heading according to his/her needs.
Change Button Type Using the buttonType property in theme object merchant can change the type of ApplePay and GooglePay buttons according to his/her needs.
Values supported by ApplePay buttonType are written here.
Values supported by GooglePay buttonType are written here.
buttonType
property is only supported by Apple Pay and Google Pay.
However, Google Pay supports an additional property buttonSizeMode
property, which can alter the Google Pay Button Size Mode. Supported values are static
and fill
. By default, fill
is selected. Using fill
allows you to change the button size, while static
sets the default size provided by Google
Change Button Color
Using the buttonColor
property in theme
object merchants can change the color of ApplePay
, GooglePay
, StcPay
, and UrPay
buttons according to his needs.
buttonColor
property is supported by applePay
, googlePay
, stcPay
, and urPay
Values supported by ApplePay
buttonColor
are white, black and white-outline
Values supported by GooglePay
buttonColor
are white and black
However, stcPay
and urPay
can supported any css
collor in buttonColor.
Example
HTML
Javascript
Is a function that shows a message in a popup on the screen. The message parameter must be a string, and the optional pg_response
parameter is an object that displays key-value pairs representing object values within the popup.
Popup will not display null values passed in the response.
typestring
he type identifies the modal that should be displayed to the customer. Supported values are error
, success
&redirect
message string
The message for a failed payment can be displayed to the customer.
pg_response object
The raw response data that was received directly from the payment gateway after the transaction attempt. This typically includes transaction status, transaction identifier, and potentially error messages or additional data provided by the gateway. pg_response
is only supported by type error
& success
Checkout.showPopup("success","Payment Successful! Redirecting you now. Please hold on.")
Checkout.showPopup(‘error’,'Selected payment method failed. Try again.' , { "merchant":"009057332", "timeOfLastUpdate":"2023-08-01T14:19:00.510Z", "version":"65" })
Checkout.showPopup(‘redirect’,’Redirecting to the payment page’)
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.
Please note that due to technical constraints associated with off-site redirection during the payment process, the successCallback
and cancelCallback
functions are only called for on-site checkouts. However, the errorCallback
function is called for any kind of payments. On-site checkouts include options such as Apple Pay, Google Pay, payments with saved cards, and on-site card form transactions, which support callback functionality for a seamless user experience.
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 a data object with a data.status value of error
Params Available in Data Object for errorCallback
message
required
form_of_payment
required
status
required
challenge_occurred
session_id
order_no
reference_number
Here's an example of how errorCallback
might be defined
In this example, the errorCallback
function is defined and passed as the value of the data-error
attribute on the Checkout script tag. If an error occurs during a payment, the function will be invoked with a data object
. This function will handle error as need and show error modal using Checkout.showPopup()
.
errorCallback
function is not required to perform a redirection. It can handle errors in any way that is appropriate for your application.
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 a data object.with a data.status value of "canceled
”
Params Available in Data Object for cancelCallback
message
form_of_payment
challenge_occurred
session_id
status
order_no
reference_number
payment_gateway_info
Here's an example of how cancelCallback
might be defined
In this example, the cancelCallback
function is defined and passed as the value of the data-cancel
attribute on the Checkout script tag. If a customer cancels a payment, the function will be invoked with a data object containing information about the cancelled transaction. This function will handle cancellation as needed and show error modal using Checkout.showPopup().
In the Checkout SDK, the successCallback
is a function triggered upon successful completion of the payment process. This callback receives a data object,with a data.status value of success
Params Available in Data Object for successCallback
message
form_of_payment
challenge_occurred
session_id
status
order_no
reference_number
redirect_url
payment_gateway_info
The successCallback
function is defined and passed as the value of the data-success attribute on the Checkout script tag. If the payment process completes successfully, the function will be invoked with a data object containing information about the completed transaction. The function will then redirect the customer to the specified redirect_url
using window.location.href
.
Here's an example of how successCallback
might be defined
To ensure the integrity of your transactions, the Checkout SDK provides a beforePayment
hook that allows you to take necessary precautions before the payment process starts. It's crucial for e-commerce platforms to implement this feature, especially when considering multi-tab operations by users.
Initialize the Hook
When initializing the SDK, you can set up the beforePayment
hook which will trigger when the payment process starts.. This hook should return a Promise. If the Promise is resolved, the user may continue with the payment process. However, if the Promise is rejected, the payment process will be halted, and an error message will appear in the browser console.
For wallet payments such as ApplePay
, GooglePay
, and STCPay
, the respective payment sheet will be presented. As soon as the payment process begins, the SDK will invoke the beforePaymen
t hook.
For other payment methods, including redirect, ottuPG
, and tokenPay
, the beforePayment
hook is triggered when the Pay
button is clicked
Params Available in Data Object for beforePayment
redirect_url
Handle Payment Outcomes
Success: Direct users to the payment success page.
Cancel/Error: It's essential to unfreeze the cart to allow the user to make changes and retry the payment. Use the cancelCallback
and errorCallback
provided by the SDK to handle these cases.
Always freeze cart updates during ongoing payment processes. This ensures users can't manipulate cart contents in parallel with a transaction, preserving transaction integrity.
Ensure that the cart is unfrozen in cases of payment cancellations or errors. This improves user experience, allowing them to adjust their cart if needed.
The data object received by the errorCallback, cancelCallback and successCallback contains information related to the payment transaction, such as the status of the payment process, the session_id generated for the transaction, any error message associated with the payment, and more. This information can be used to handle the payment process and take appropriate actions based on the status of the transaction.
string
It is a string message that can be displayed to the customer. It provides a customer-friendly message regarding the status of the payment transaction.
string
It is a unique identifier generated when a payment transaction is created. It is used to associate a payment transaction with the checkout process. You can find the session_id
in the response of the Checkout API's session_id endpoint. This parameter is required to initialize the Checkout SDK.
string
It is of the checkout process. Possible values are:
success
: The customer was charged successfully, and they can be redirected to a success page or display a success message.
canceled
: The payment was either canceled by the customer or rejected by the payment gateway for some reason. When a payment is canceled, it's typically not necessary to create a new payment transaction, and the same session_id can be reused to initiate the Checkout SDK and allow the customer to try again. By reusing the same session_id, the customer can resume the checkout process without having to re-enter their payment information or start over from the beginning.
error
: An error occurred during the payment process, This can happen for a variety of reasons, such as a network failure or a problem with the payment gateway's system. The recommended action is to create a new payment transaction using the Checkout API and restart the checkout process.
URL
The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. order_no, reference_number and session_id will be appended to the redirect URL as query parameters. The developer implementing the SDK must ensure that the redirection process is smooth and secure, providing a seamless experience for the customer while maintaining the integrity of the payment process.
It's important to note that while the redirect_url
option is typically present only in the successCallback, there are specific cases where it may exist in failure scenarios.
For example, in the event of an MPGS cancel or if the transaction includes a webhook URL
alongside a redirect URL
, users may be redirected after cancellation, which is communicated to the webhook. Therefore, the presence of redirect_url
in such cases is possible.
string
The order number provided in the Checkout API. See Checkout API & order_no.
string
A unique identifier associated with the payment process. It is sent to the payment gateway as a unique reference and can be used for reconciliation purposes.
string
Enum: apple_pay
, google_pay
, token_pay
, stc_pay
, redirect
Indicates the form of payment used to process the transaction. This can be one of several options, including apple_pay
, google_pay
, token_pay
, stc_pay
, or redirect
. It's important to note that the redirect option is only present in the errorCallback
. In other scenarios, especially with cancelCallback
and successCallback
, it's absent. This is because, in the redirect flow, the customer is redirected to a different page where actions like payment cancellation or confirmation occur, not on the page where the SDK is displayed.
apple_pay
- Apple Pay
google_pay
- Google Pay
token_pay
- Token Pay
stc_pay
- stc pay
redirect
- Redirect
object
Information about the payment gateway, accompanied by the response received from the payment gateway
string
The unique identifier, or pg_code
, for the payment gateway that was used to process the payment. This value corresponds to the specific payment method utilized by the customer, such as credit-card
.
string
The name of the payment gateway, represented in all lowercase letters, that was used to perform the payment. This could be one of several values, such as kpay
(for KNET), mpgs
, or cybersource
. These identifiers provide a human-readable way to understand the payment mechanism that was utilized.
object
The raw response data that was received directly from the payment gateway after the transaction attempt. This typically includes transaction status, transaction identifier, and potentially error messages or additional data provided by the gateway.
bool
Default: false
This flag indicates if an additional verification, such as 3DS, OTP, PIN, etc., was initiated during the payment process. Use this flag in cancelCallback
and errorCallback
to control the presentation of error messages, especially for on-site payments undergoing a challenge flow. For example, after a failed 3DS verification, it's useful to show a custom popup informing the user of the payment failure. However, it's crucial to note that not all on-site failed payments need custom error messaging. In cases like GooglePay
or ApplePay
, error messages are inherently handled by the Payment Sheet, which remains open for the user to retry, making this distinction vital.