Ottu Web SDK

Last updated 1 year ago

Ottu Web SDK

The is a JavaScript library provided by Ottu that allows you to easily integrate an Ottu-powered 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 , , and You can also specify additional options such as, which forms of payment to accept, the styling for the checkout interface, and more.

Please note that the Checkout SDK requires the implementation of the 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:

<head>
    <script src="https://assets.ottu.net/checkout/v2/checkout.min.js" 
     data-error="errorCallback" data-cancel="cancelCallback"
     data-success="successCallback" 
     data-beforeredirect="beforeRedirect"></script>
 </head>

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:

Checkout.reload();

In this example, the Checkout.reload function is called to refresh the content of the SDK. This can be useful when an error has occurred and the content needs to be reloaded or refreshed.

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:

<div id="checkout"></div>

In this example, the id attribute of the <div> element is set to "checkout". This means that the selector property in Checkout.init should be set to "checkout".

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:

Checkout.init({
    selector: 'checkout', 
    ... // other properties
});

In this example, the selector property is set to "checkout", which means that the checkout form will be contained in the <div> element with id="checkout".

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 session_id is the unique identifier for the payment transaction associated with the checkout process.

The lang property is used to specify the language in which the checkout elements should be displayed. This property can be set to either "en" (for English) or "ar" (for Arabic).

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.

This property can be particularly useful when you want to customize the checkout process and display only specific forms of payment, such as only displaying the Apple Pay button and hiding the other payment options.

css can be used to override some of the elements rendered by the SDK to better integrate with your website.

.ottu__sdk-main: the class of the div which wraps all the elements of the container. It's useful to override this when you want to modify the size of the rendered content by the SDK.
.apple-pay-button: the class of the Apple Pay button, which is a div. It can be customized for width, padding, margin, and more. Useful to customize when formsOfPayment is configured to display only the Apple Pay button.

Checkout.init({
    selector: 'checkout',
    merchant_id: 'domain',
    session_id: 'session_id',
    apiKey: 'api_key',
    formsOfPayment: ['applePay', 'tokenPay', 'redirect'],
    css: `
    .ottu__sdk-main {
      flex-basis: 100%;
      justify-content: center;
      width: 150px!important;
      max-width: 150px!important;
    }
    .ottu__sdk-apple-pay-button-type {
      -apple-pay-button-type: check-out;
    }
    .apple-pay-button {
      width: 90%;
      padding-top: 0px;
      margin-top: 12px;
      margin-bottom: 12px;
    }
  `
});

buttonStyles objectThe buttonStyle is an object in the Google Pay API that enables merchants to customize the default styling properties of the Google Pay button. This object provides options to modify the width, margin-top, and margin-bottom of the button. By utilizing the ButtonStyle object, merchants can tailor the appearance of the Google Pay button to align with their website or app design. Default css is: width: 90%, margin-top: 12px, margin-bottom: 12px.

Example

To display only the Google Pay button, use the following code:

Checkout.init({
      selector: "checkout",
      merchant_id:"merchant.ottu.dev",
	formsOfPayment: ["googlePay"],
	// ...mandatory properties,
googlePayInit: {
 		apiVersion: 2,
 		apiVersionMinor: 0,
 		allowedCardNetworks: ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"],
 		allowedCardAuthMethods:  ["PAN_ONLY", "CRYPTOGRAM_3DS"],
 		tokenizationSpecificationType: 'PAYMENT_GATEWAY',
 		totalPriceStatus: 'FINAL',
 		totalPriceLabel: 'TOTAL',
 		buttonType: 'buy',
 		buttonLocale: 'en',
 		buttonStyles: {
   			'width': '90% !important',
   			'margin-top': '12px !important',
   			'margin-bottom': '12px !important',
 		}
},
}

Example

HTML

<div id="checkout"></div>

Javascript

Checkout.init({
    selector: "checkout",
    merchant_id: "",
    session_id: "",
    apiKey: "",
    lang: "en",
    formsOfPayment: ['applePay', 'tokenPay', 'ottuPG', 'redirect', 'googlePay', 'stcPay']
    css: `
        ottu__sdk-main {
        flex-basis: 100%;
        justify-content: center;
        width: 150px!important;
        max-width: 150px!important;
    }`
});

Is a function that shows an error 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.

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.

Example

Checkout.showErrorPopup('Selected payment method failed. Try again.' , { "merchant":"009057332", "timeOfLastUpdate":"2023-08-01T14:19:00.510Z", "version":"65" })

Checkout.showErrorPopup('Selected payment method failed. Try again.' , cancel.payment_gateway_info.pg_response)

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.

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 an error object.

The error object has the following properties:

status: A string indicating the status of the payment transaction. The only value that will be passed to the errorCallback is "error".
message: A string containing a description of the error that occurred.

Here's an example of how errorCallback might be defined:

<head>
    <script src="https://assets.ottu.net/checkout/v2/checkout.min.js" data-error="errorCallback"></script>
    <script>
        function errorCallback(error) {
          console.log(error);
          // handle error - redirect to payment page
          window.location.href = "https://payment.example.com";
        }
    </script>
</head>

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 an error object. The function will then handle the error as needed and redirect the customer to https://payment.example.com.

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.

Here's an example of how cancelCallback might be defined:

window.cancelCallback = function (data) {
    console.log(data);
    // handle cancellation
    Checkout.reload();
};

The successCallback in the Checkout SDK is a callback function that is invoked when the payment process has been completed successfully.

Here's an example of how successCallback might be defined:

window.successCallback = function (data) {
    window.location.href = data.redirect_url;
};

Example

window.successCallback = function (data) {
    data = {
        "status": "success",
        "message": "Payment operation completed successfully.",
        "session_id": "",
        "order_no": "",
        "operation": "pay",
        "reference_number": "",
        "redirect_url": "https://payment.example.com/success"
    };

    window.location.href = data.redirect_url;
};

For redirect checkout processes, you may want to freeze the customer's basket before the customer is redirected to the payment page. The Checkout SDK provides a beforeRedirect callback that you can use to perform any necessary actions before the redirection occurs.

Here's an example of how to define the beforeRedirect callback:

<head>
    <script src="https://assets.ottu.net/checkout/v2/checkout.min.js" data-beforeredirect="beforeRedirect"></script>
    <script>
        window.beforeRedirect = function() {
            // Freeze the customer's basket while waiting for an API response
            return new Promise(function(resolve, reject) {
                // Send a request to your API to freeze the customer's basket
                fetch('https://api.yourdomain.com/basket/freeze', {
                        method: 'POST'
                    })
                    .then(function(response) {
                        // If the API response is successful, resolve the Promise
                        if (response.ok) {
                            resolve(true);
                        } else {
                            // If the API response fails, reject the Promise
                            reject(new Error('Failed to freeze basket'));
                        }
                    })
                    .catch(function(error) {
                        // If the API request fails, reject the Promise
                        reject(error);
                    });
            });
        }
    </script>
</head>

In this example, the beforeRedirect callback sends a request to an API endpoint to freeze the customer's basket while waiting for the redirection to occur. If the API response is successful, the Promise is resolved and the redirection proceeds. If the API request fails or the response is unsuccessful, the Promise is rejected and the redirection is cancelled.

Data object child parameters
- messagestring
  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.
- status 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.
  - 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.
- reference_numberstring
  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.
- form_of_payment string
  The form of payment which was used to process the payment. This could be one of several values, such as Enum: "apple_pay", "google_pay", "token_pay", "stc_pay".
- payment_gateway_info object Information about the payment gateway, accompanied by the response received from the payment gateway
  - pg_code 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.
  - pg_name 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.
  - 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.

<!-- HTML -->
<div id="checkout"></div>
<script src="https://assets.ottu.net/checkout/v2/checkout.min.js"
  data-error="errorCallback"
  data-success="successCallback"
  data-cancel="cancelCallback">
</script>

// JS
// Error callback function
window.errorCallback = function(error) {
  let validFormsOfPayments = ['apple_pay', 'google_pay' , 'stc_pay'];
  if (!validFormsOfPayments.includes(error.form_of_payment)) {
    const message = "Oops, something went wrong. Refresh the page and try again.";
    window.Checkout.showErrorPopup(error.message || message);
  }
  console.log('Error callback', error);
};

// Success callback function
window.successCallback = function(success) {
  window.location.href = success.redirect_url;
};

// Cancel callback function
window.cancelCallback = function(cancel) {
  if (cancel.payment_gateway_info && cancel.payment_gateway_info.pg_name === "kpay") {
    window.Checkout.showErrorPopup('', cancel.payment_gateway_info.pg_response);
  }
  console.log('Cancel callback', cancel);
};

// Checkout init function
Checkout.init({
  selector: "checkout",
  merchant_id: "sandbox.ottu.net",
  session_id: "51436d465f77e59242ef25f15409c2f23fe54761",
  apiKey: "3bf2a041d0896419415feac3228b17e3ec53e793",
  lang: "en", // en or ar default en
  formsOfPayments: ['applePay', 'googlePay', 'stcPay', 'ottuPG', 'tokenPay', 'redirect'],
  css: `ottu__sdk-main {
    flex-basis: 100%;
    justify-content: center;
    width: 150px!important;
    max-width: 150px!important;
  }
  .apple-pay-button {
    width: 90%;
    margin-top: 12px;
    margin-bottom: 12px;
  }`,
  googlePayInit: {
    apiVersion: 2,
    apiVersionMinor: 0,
    allowedCardNetworks: ['AMEX', 'DISCOVER', 'INTERAC', 'JCB', 'MASTERCARD', 'VISA'],
    allowedCardAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
    tokenizationSpecificationType: 'PAYMENT_GATEWAY',
    baseCardPaymentMethodType: null,
    paymentsClient: null,
    totalPriceStatus: 'FINAL',
    totalPriceLabel: 'Total',
    buttonType: 'buy',
    buttonLocale: 'en',
    buttonStyles: {
      'width': '90%',
      'margin-top': '12px',
      'margin-bottom': '12px',
    },
  },
});

The customer has an Apple device that supports Apple Pay payments.
The browser being used supports Apple Pay.
The customer has a wallet configured on their Apple Pay device.

To display only the Apple Pay button with default css, use the following code:

Checkout.init({
    ... // define the mandatory properties
   formsOfPayment: ["applePay"]
});

Checkout.init({
    ... // define the mandatory properties
    formsOfPayment: ["applePay"],
    css: `
        .ottu__sdk-main {
            flex-basis: 100%;
            justify-content: center;
            width: 150px!important;
            max-width: 150px!important;
        }
        .ottu__sdk-apple-pay-button-type {
            -apple-pay-button-type: check-out;
        }
        .apple-pay-button {
            width:100%;
            padding-top:0px;
            margin-top:18px;
            margin-bottom:18px;
        }
    `
});

.ottu__sdk-apple-pay-button-type: This class determines the type of the Apple Pay button. For example, setting -apple-pay-button-type: plain will render a plain Apple Pay button, while setting it to buy or donate will render buttons with the corresponding labels.
.apple-pay-button: This class sets the width, margin, and padding of the button.

By default, the width of the Apple Pay button is 90% of the Checkout SDK container width, with top and bottom margins of 12px. The Checkout SDK creates a containerized div with the css class ottu__sdk-main and places the Apple Pay button inside it. This container has no margin or padding added, as shown in below figure.

If you have completed the Google Pay integration between Ottu and Google Pay, the Checkout SDK will handle the necessary checks to display the Google Pay button seamlessly.

The session_id and pg_codes provided during SDK initialization must be associated with the Google Pay Payment Service. This ensures that the Google Pay option is available for the customer to choose as a payment method.
Web SDK checks if the merchant configuration for Google Pay is correct or not and then show Google Pay button based on it.
The Web SDK displays the Google Pay button irrespective of whether the customer's Google Pay wallet is configured. When the customer clicks the button, they are prompted to log in with their email and add their card if their wallet is not set up.

Customize Google Pay button

Due to compliance requirements, KNET requires a popup displaying the payment result after each failed payment. This is available only on the cancelCallback when there is a response from the payment gateway. As a side effect, the user can not try again the payment without clicking on Apple Pay again.

The use of the popup notification described above is specific to the KNET payment gateway. Other payment gateways might have different requirements or notification mechanisms, so be sure to follow the respective documentation for each payment gateway integration.

To properly handle the popup notification for KNET, you need to implement the provided code snippet into your payment processing flow. The code looks like this:

window.cancelCallback = function(cancel) {
  if (cancel.payment_gateway_info && cancel.payment_gateway_info.pg_name === "kpay") {
    const errorMessage = cancel.payment_gateway_info.pg_response || "Payment was cancelled.";
    window.Checkout.showErrorPopup(errorMessage);
  }
  console.log('Cancel callback', cancel);
};

The above code performs the following checks and actions:

It first verifies if the cancel object contains information about the payment gateway (payment_gateway_info).
Next, it checks if the pg_name property in payment_gateway_info is equal to "kpay", indicating that the payment gateway used is indeed KNET.
If the above conditions are met, it retrieves the payment gateway's response from the pg_response property or, if not available, uses a default "Payment was cancelled." error message.
Finally, it displays the error message in a popup using the window.Checkout.showErrorPopup() function to notify the user about the failed payment.

Last updated 1 year ago

Ottu Web SDK

Ottu Web SDK

Example

message`string`

reference_number`string`

form_of_payment `string`

`string`

`string`

`string`

`string`

`array`

`object`

`object`

Example

message`string`

reference_number`string`

form_of_payment `string`

`string`

`string`

`string`

`string`

`array`

`object`

`object`

Example

messagestring

reference_numberstring

form_of_payment string

string

string

string

string

array

object

object

Example

messagestring

reference_numberstring

form_of_payment string

string

string

string

string

array

object

object

message`string`

reference_number`string`

form_of_payment `string`

`string`

`string`

`string`

`string`

`array`

`object`

`object`

message`string`

reference_number`string`

form_of_payment `string`

`string`

`string`

`string`

`string`

`array`

`object`

`object`