Web V3

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

Checkout SDK

Demo

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.

Installation

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/v3/checkout.min.js" 
   data-error="errorCallback" data-cancel="cancelCallback"
   data-success="successCallback" 
   data-before-redirect="beforeRedirect"></script>
</head>

Replace errorCallback, cancelCallback, successCallback, and beforeRedirect with the names of your error handling, cancel handling, success handling, and before-redirect 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.

Functions

Checkout.init

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.

Checkout.reload

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.

Properties

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

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

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

apiKey

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.

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

lang string

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

When lang is set to "en", the checkout form will be displayed in English, and when it's set to "ar", the checkout elements will be displayed in Arabic. Additionally, when the lang parameter is set to "ar", the layout will switch to right-to-left (RTL) to accommodate Arabic script. For more information on how to use lang parameter in the Checkout API, see lang.

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

displayMode string

In SDK v3, 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

  • grid

    In grid mode, saved cards will appear on the left side and the redirect links on the right side.

Checkout.init({
  selector: "checkout",
  merchant_id: 'domain',
  session_id: 'session_id',
  apiKey: 'apiKey',
  // Default mode is Grid
  displayMode: 'grid'
});

  • column

    Default displayMode will be column, where all forms of payment appear one under another, similar to a responsive view.

Checkout.init({
  selector: "checkout",
  merchant_id: 'domain',
  session_id: 'session_id',
  apiKey: 'apiKey',
  // Default Mode is Column
  displayMode: 'column'
});

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

  • buttonType

    Users can change Apple Pay Button Type by using buttonType property. Values supported by buttonType are written here.

  • supportedNetworks

    The payment networks that the merchant supports. Users can change supportedNetworks by using supportedNetworks property.Values supported by supportedNetworks are written here.

  • merchantCapabilities

    An array of the payment capabilities that the merchant supports, such as credit or debit.Users can change merchantCapabilities by using merchantCapabilities property. Values supported by merchantCapabilities are written here.

Checkout.init({
  selector: "checkout",
  merchant_id: 'domain',
  session_id: 'session_id',
  apiKey: 'apiKey',
  // Below are the default values configured for applePay
  applePayInit: {
    buttonType: 'plain',
    supportedNetworks: ['amex', 'masterCard', 'maestro', 'visa', 'mada'],
    merchantCapabilities: ['supports3DS']
  }
});

googlePayInit 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 by utilizing the options outlined in the documentation here.

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',
    buttonColor: 'white'
  }
});

theme 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

Checkout.init({
  selector: "checkout",
  merchant_id: 'domain',
  session_id: 'session_id',
  apiKey: 'apiKey',
  theme: {
    'pay-button': {
      'background': 'black'
    }
  }
});

Here are some example themes that you can use

  • Sample Theme

Checkout.init({
  selector: "checkout",
  merchant_id: 'domain',
  session_id: 'session_id',
  apiKey: 'apiKey',
  theme: {
    "main": {
      "padding": "0px 10px",
      "background": "#d4d4d461"
    },
    "primary-text": {
      "color": "black",
      "background": "red"
    },
    "pay-button": {
      "background": "black",
      "color": "white"
    },
    "amount-box": {
      "background": "#1157e878"
    },
    "methods": {
      "background": "#373f5236"
    },
    "checkbox-label": {
      "color": "#003aff"
    }
  }
});

  • Dark Theme

Checkout.init({
  selector: "checkout",
  merchant_id: 'domain',
  session_id: 'session_id',
  apiKey: 'apiKey',
  theme: {
    "main": {
      "padding": "0px 10px",
      "background": "#555555"
    },
    "title-text": {
      "color": "white"
    },
    "primary-text": {
      "color": "white"
    },
    "secondary-text": {
      "color": "white"
    },
    "pay-button": {
      "background": "#333",
      "color": "white"
    },
    "amount-box": {
      "background": "#333"
    },
    "stcPay": {
      "background": "black"
    },
    "stc-modal": {
      "background": "black"
    },
    "stc-input": {
      "color": "black"
    },
    "methods": {
      "background": "#333"
    },
    "selected-method": {
      "background": "black",
      "border": "2px solid #6e6ef5d4",
    },
    "card-removal-modal": {
      "background": "black"
    },
    "keep-card-button": {
      "color": "black"
    },
    "info-modal": {
      "background": "black"
    },
    "error-retry-button": {
      "color": "black"
    },
    "ccv-input": {
      "background": "black",
      "color": "white"
    },
    "floating-label": {
      "background": "black"
    },
    "stc-popup-error": {
      "color": "red"
    },
    "stc-popup-back-button": {
      "stroke": "red"
    },
    "popup-close-button": {
      "fill": "red"
    },
    "stc-resendOtp-button": {
      "color": "black"
    }
  }
})

  • Minimal Theme

Checkout.init({
  selector: "checkout",
  merchant_id: 'domain',
  session_id: 'session_id',
  apiKey: 'apiKey',
  theme: {
    "title-text": {
      "font-family": "SF PRO REGULAR"
    },
    "primary-text": {
      "font-family": "SF PRO REGULAR"
    },
    "secondary-text": {
      "font-family": "SF PRO REGULAR"
    },
    "amount-box": {
      "background": "transparent"
    },
    "methods": {
      "background": "transparent",
      "border": "none"
    },
    "selected-method": {
      "background": "transparent",
      "border": "none"
    },
    "ccv-input": {
      "background": "transparent"
    },
    "floating-label": {
      "background": "white"
    }
  }
});

  • Side By Side Buttone

Checkout.init({
  selector: "checkout",
  merchant_id: 'domain',
  session_id: 'session_id',
  apiKey: 'apiKey',
  googlePayInit: {
    buttonColor: ”black”
  },
  theme: {
    "wallet-buttons": {
      "flex-direction": "row",
      "gap": "10px"
    },
    "stcPay": {
      "background": "black"
    }
  }
})

  • Hide SDK Header

Checkout.init({
  selector: "checkout",
  merchant_id: 'domain',
  session_id: 'session_id',
  apiKey: 'apiKey',
  theme: {
    "title-text": {
      "display": "none"
    },
    "amount-box": {
      "display": "none"
    }
  }
});

Supported Values

Example

HTML

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

Javascript

Checkout.init({
  selector: "checkout",
  merchant_id: "",
  session_id: "",
  apiKey: "",
  displayMode: "grid",
  lang: "en",
  formsOfPayment: ['applePay', 'tokenPay', 'ottuPG', 'redirect', 'googlePay', 'stcPay'],
  theme: {
    main: {
      'flex-basis': '100%',
      'justify-content': 'center',
      'width': '100%',
      'max-width': '100%',
    }
  }
});

Checkout.showPopup(type, message, response)

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.

  • 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

Example

Checkout.showPopup("success","Please wait while we redirect you to merchants page")

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 payment page’')

Callbacks

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.

window.errorCallback

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

window.errorCallback = function(data) {
  // If the payment fails with the status "error," the SDK triggers the errorCallback.
  // In errorCallback, we show an error popup by checking if form_of_payment in data
  // is "token_pay" or "redirect".
  const validFormsOfPayments = ['token_pay', 'redirect'];
  if (validFormsOfPayments.includes(data.form_of_payment) || data.challenge_occurred) {
    const message = "Oops, something went wrong. Refresh the page and try again.";
    // Displays a popup with data.message if present; else, it displays a static message.
    window.Checkout.showPopup("error",data.message || message);
  }
  console.log('Error callback', data);
}

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

window.cancelCallback

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.

cancelCallback receives a data object, where the data.status is "canceled".

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

window.cancelCallback = function(data) {
  // If the payment fails with the status "canceled," the SDK triggers the cancelCallback.
  // In cancelCallback, we show an error popup by checking if pg_name
  // in data.payment_gateway_info is "kpay" or data.form_of_payment is "token_pay".
  if (data.payment_gateway_info && data.payment_gateway_info.pg_name === "kpay") {
    // Displays a popup with pg_response as key-value pairs.
    window.Checkout.showPopup("error", " ", data.payment_gateway_info.pg_response);
  } else if (data.form_of_payment === 'token_pay' || data.challenge_occurred) {
    const message = "Oops, something went wrong. Refresh the page and try again.";
    // Displays a popup with data.message if present; else, it displays a static message.
    window.Checkout.showPopup("error", data.message || message);
  }
  console.log('Cancel callback', data);
}

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 need and show error modal using Checkout.showPopup().

window.successCallback

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) {
  //If payment gets completed with status “success” 
  //SDK triggers the successCallback,In successCallback 
  //we redirect the user to data.redirect_url
  window.location.href = data.redirect_url
}

successCallback receives a data object, where the data.status is "success".

In this example, 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.

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;
};

window.beforeRedirect

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.

To define the beforeRedirect callback, you can use the data-beforeredirect attribute on the Checkout script tag to specify a global function that will handle the callback. This function should return a Promise that resolves when the necessary actions are complete.

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

window.beforeRedirect = function(response) {
  return new Promise(function(resolve) {
    // Displays a redirect popup before redirecting to the payment page
    window.Checkout.showPopup("redirect", response.message || 'Redirecting to the payment page', null);
    resolve();
  });
}

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

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.

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.

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

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

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

  • redirect_url URL

    This field provides the URL to which the customer should be redirected in order to complete the payment process when they have selected this specific payment method. 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 the redirect_url option is only present in the successCallback. In other scenarios, especially with cancelCallback and errorCallback, it's absent.

  • order_no string

    The order number provided in the Checkout API. See Checkout API & order_no.

  • 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

    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

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

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

Example Without googlePayInit/ApplePayInit

window.errorCallback = function(data) {
  // If payment fails with the status "error," SDK triggers the errorCallback.
  // In errorCallback, we show an error popup by checking if form_of_payment in data is "token_pay" or "redirect".
  const validFormsOfPayments = ['token_pay', 'redirect'];
  if (validFormsOfPayments.includes(data.form_of_payment) || data.challenge_occurred) {
    const message = "Oops, something went wrong. Refresh the page and try again.";
    // Displays a popup with data.message if present; else, it displays a static message.
    window.Checkout.showPopup("error",  data.message);
  }
  console.log('Error callback', data);
};

window.successCallback = function(data) {
  // If payment gets completed with the status "success," SDK triggers the successCallback.
  // In successCallback, we redirect the user to data.redirect_url.
  window.location.href = data.redirect_url;
};

window.cancelCallback = function(data) {
  // If payment fails with the status "canceled," SDK triggers the cancelCallback.
  // In cancelCallback, we show an error popup by checking if pg_name in data.payment_gateway_info is "kpay" or data.form_of_payment is "token_pay".
  if (data.payment_gateway_info && data.payment_gateway_info.pg_name === "kpay") {
    // Displays a popup with pg_response as key-value pairs.
    window.Checkout.showPopup("error", " ", data.payment_gateway_info.pg_response);
  } else if (data.form_of_payment === "token_pay" || data.challenge_occurred) {
    const message = "Oops, something went wrong. Refresh the page and try again.";
    // Displays a popup with data.message if present; else, it displays a static message.
    window.Checkout.showPopup("error",data.message || message);
  }
  console.log('Cancel callback', data);
};

Checkout.init({
  selector: "checkout",
  merchant_id: 'sandbox.ottu.net',
  session_id: '51436d465f77e59242ef25f15409c2f23fe54761',
  apiKey: '3bf2a041d0896419415feac3228b17e3ec53e793',
  lang: 'en',
  displayMode: 'grid', // default is column
  theme: {
    main: {
      'flex-basis': '100%',
      'justify-content': 'center',
      width: '100%',
      'max-width': '100%',
    }
  }
});

Extended example

HTML

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

JS

window.errorCallback = function(data) {
  // If payment fails with status "error," SDK triggers the errorCallback.
  // In errorCallback, we show an error popup by checking if form_of_payment in data is "token_pay" or "redirect".
  const validFormsOfPayments = ['token_pay', 'redirect'];
  if (validFormsOfPayments.includes(data.form_of_payment) || data.challenge_occurred) {
    const message = "Oops, something went wrong. Refresh the page and try again.";
    // Displays a popup with data.message if present; else, it displays a static message.
    window.Checkout.showPopup("error", data.message || message);
  }
  console.log('Error callback', data);
};

window.successCallback = function(data) {
  // If payment gets completed with status "success," SDK triggers the successCallback.
  // In successCallback, we redirect the user to data.redirect_url.
  window.location.href = data.redirect_url;
};

window.cancelCallback = function(data) {
  // If payment fails with status "canceled," SDK triggers the cancelCallback.
  // In cancelCallback, we show an error popup by checking if pg_name is in data.
  // payment_gateway_info is "kpay" or data.form_of_payment is "token_pay".
  if (data.payment_gateway_info && data.payment_gateway_info.pg_name === "kpay") {
    // Displays a popup with pg_response as key-value pairs.
    window.Checkout.showPopup("error", '', data.payment_gateway_info.pg_response);
  } else if (data.form_of_payment === "token_pay" || data.challenge_occurred) {
    const message = "Oops, something went wrong. Refresh the page and try again.";
    // Displays a popup with data.message if present; else, it displays a static message.
    window.Checkout.showPopup("error", data.message || message);
  }
  console.log('Cancel callback', data);
};

window.beforeRedirect = function(response) {
  return new Promise(function(resolve) {
    window.Checkout.showPopup("redirect", response.message || 'Redirecting to the payment page', null);
    resolve();
  });
};

JS

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'],
  displayMode: 'grid', // default is column
  theme: {
    main: {
      'flex-basis': '100%',
      'justify-content': 'center',
      width: '100%',
      'max-width': '100%',
    }
  },
  applePayInit: {
    buttonType: 'plain',
    supportedNetworks: ['amex', 'masterCard', 'maestro', 'visa', 'mada'],
    merchantCapabilities: ['supports3DS'],
  },
  googlePayInit: {
    apiVersion: 2,
    apiVersionMinor: 0,
    allowedCardNetworks: ['AMEX', 'DISCOVER', 'INTERAC', 'JCB', 'MASTERCARD', 'VISA'],
    allowedCardAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
    tokenizationSpecificationType: 'PAYMENT_GATEWAY',
    baseCardPaymentMethodType: '',
    paymentsClient: null,
    totalPriceStatus: 'FINAL',
    totalPriceLabel: 'Total',
    buttonType: 'buy',
    buttonLocale: 'en',
    buttonColor: 'white',
  }
});

Apple Pay

If you have completed the Apple Pay integration between Ottu and Apple, the Checkout SDK will automatically make the necessary checks to display the Apple Pay button.

When you initialize the Checkout SDK with your session_id and payment gateway codes, the SDK will automatically verify the following conditions:

  • When initializing the Checkout SDK, a session_id with a pg_codes that was associated with the Apple Pay Payment Service was supplied.

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

If all of these conditions are met, the Apple Pay button will be displayed and available for use in your checkout flow. If the wallet is not configured, the Apple Pay button will still appear, but with setUp type. Clicking on the setUp button Apple Pay wallet on their device will open, allowing them to configure it and add payment cards.

By default, the type of the Apple Pay button is pay, which is used to initiate a payment. However, you can override the default button type using the css init property of the Checkout SDK.

Customize Apple Pay button

If you're using only the Apple Pay button from the Checkout SDK and want to customize its appearance, it's important to follow the Apple Pay guidelines to ensure that your design is consistent with Apple's requirements. Failure to follow the guidelines could result in your app being rejected or your developer account being banned by Apple.

It's the responsibility of the merchant to ensure that their use of the Apple Pay button follows Apple's guidelines, and Ottu cannot be held responsible for any issues that arise from non-compliance. If you have any questions or concerns about using the Apple Pay button, please consult the Apple Pay guidelines or contact Apple directly for assistance.

If you only want to use Apple Pay with the Ottu Checkout SDK and control the other payment methods yourself, you can customize the Apple Pay button using the Checkout SDK's formsOfPayment and css properties.

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

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

The formsOfPayment property tells the Checkout SDK to render only the Apple Pay button. If you don't include this property, the SDK will render all available payment options.

To customize the Apple Pay button's appearance, you can use the theme property. The example below adjusts the size of the button and centers it within the Checkout SDK container:

Checkout.init({
  // Define the mandatory properties
  formsOfPayment: ["applePay"],
  applePayInit: {
    buttonType: 'donate',
  },
  theme: {
    applePay: {
      "width": '100%',
      "height": '50px',
      "margin-top": '0',
      "margin-bottom": '0',
    }
  }
});

The Apple Pay button inside the Checkout SDK container can be customized using the theme property by defining the following:

  • applePayInit.buttonType: This determines the type of the Apple Pay button. For example, setting buttonType: plainwill render a plain Apple Pay button, while setting it to buyor donatewill render buttons with the corresponding labels.

  • theme.applePay: This class sets the width,height, margin, and padding of the button.

By default, the width of the Apple Pay button is 100% of the Checkout SDK container width, gap of 8px between wallets buttons. 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

To learn more about the Apple Pay property, see the theme.

Google Pay

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.

When you initialize the Checkout SDK with your session_id and payment gateway codes pg_codes , the SDK will automatically verify the following conditions:

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

Google Pay configuration is controlled by using googlePayInit object.

Customize Google Pay button

You can customize the Google Pay button using the Checkout SDK's formsOfPayment . The formsOfPayment property tells the Checkout SDK to render only the Google Pay button. If you don't include this property, the SDK will render all available payment options.

Checkout.init({
  selector: "checkout",
  merchant_id: 'delta.ottu.com',
  session_id: 'session_id',
  apiKey: 'beeded69e220af16bc660a7dd57349ba0ff32d74',
  formsOfPayment: ["googlePay"],
  // Below are the default values configured for googlePay
  googlePayInit: {
    buttonType: 'donate',
  },
  theme: {
    googlePay: {
      "width": "100%",
      "height": "50px",
      "margin-top": "0",
      "margin-bottom": "0",
    }
  }
});

KNET - Apple Pay

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(data) {
  // If payment fails with status "canceled," SDK triggers the cancelCallback.
  // In cancelCallback, we show an error popup by checking if pg_name is in data.
  // payment_gateway_info is "kpay" or data.form_of_payment is "token_pay".

  if (data.payment_gateway_info && data.payment_gateway_info.pg_name === "kpay") {
    // Displays a popup with pg_response as key-value pairs.
    window.Checkout.showPopup("error", " ", data.payment_gateway_info.pg_response);
  } else if (data.form_of_payment === 'token_pay' || data.challenge_occurred) {
    const message = "Oops, something went wrong. Refresh the page and try again.";
    // Displays a popup with data.message if present, else displays a static message.
    window.Checkout.showPopup("error", data.message || message);
  }

  console.log('Cancel callback ', data);
}

The above code performs the following checks and actions:

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

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

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

  4. Finally, it displays the error message in a popup using the window.Checkout.showPopup() function to notify the user about the failed payment.

PreviousWebNextiOS

Last updated