Home
Guides
Login

SDK & UI library

Suggest Edits

Software Development Kits

Our SDKs remove the need to handle sensitive data by enabling you to validate and encrypt your data and finally create a checkout request. Check the out here:

Checkout JavaScript Library

The Checkout JavaScript Library is small library that makes creating an Express experience (modal / redirect) easier.

👍

For the best experience on Express modal checkout we highly recommend the use of this library.

Installation

Adding the library is as easy as adding a JavaScript tag. Simply add the CDN link https://cdn.cellulant.africa/js/tingg-checkout-library.js via a JavaScript tag. See the example below:

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  
  <body>
    ...
    <script src="https://cdn.cellulant.africa/js/tingg-checkout-library.js"></script>
  </body>
</html>

The script adds a Tingg object on the browser's window object. Accessing window.Tingg exposes some APIs used to render the Express checkout UI.

Usage

After the CDN has been included, add a button i.e "PAY NOW" that will trigger a HTTP request to your back-end endpoint that returns a checkout URL.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <main>
      <button id="pay-button" onclick="createCheckoutRequest()">
      PAY NOW!
      </button>
    </main>
    <script src="https://cdn.cellulant.africa/js/tingg-checkout-library.js"></script>
    <script>
      function createCheckoutRequest() {
         // 1. Create your checkout payload
         var payload = {
             customer_first_name: "John",
             customer_last_name: "Doe",
             msisdn: "254700000000",
             account_number: "ref-qwerty",
             request_amount: "100",
             merchant_transaction_id: "1234567890",
             service_code: "<YOUR TINGG SERVICE CODE>",
             country_code: "KEN",
             currency_code: "KES",
             callback_url: "https://webhook.site/...",
             fail_redirect_url: "https://webhook.site/...",
             success_redirect_url: "https://webhook.site/.."
      
         };
         
       	// 2. Create a payment URL on the server
         const req = window.fetch('<YOUR ENCRYPTION ENDPOINT>', {
           method: "POST", 
           body: JSON.stringify(payload)
         });
         
         if (!req.ok) {
         	console.log("Request failed. Payload could not be encrypted...");
           return;
         }
         
         req
           .then(fucntion (resp) {
           	 return resp.json()
         	})
           .then(function (data) {
           		window.Tingg.renderCheckout({            
                 environment: "testing",
                 checkout_type: "modal",
                 checkout_url: {
                   long_url: data.long_url,
                   short_url: data.short_url
                 },
                 onClose: () => {
                   console.log("Close called!");
                   window.Tingg.close();
                 },
                 onSuccess: (data) => {
                   console.log("Success", data);
                 },
                 onFailed: (data) => {
                   console.log("Failed", data);
                 }
               });
           }) 
       }
    </script>
  </body>
</html>

🚧

For the callback functions to take effect, the success_redirect_url & fail_redirect_url need to have the same domain origin with your e-commerce site.

Example: If your e-commerce shop/ site has the domain https://acme.example/checkout then the **success_redirect_url** and **fail_redirect_url** should start with the SAME domain i.e https://acme.example/... for the onSuccess and onFailed callbacks to be triggered.

onClose() function

This function is called when the close button is clicked. To close the modal, you'll have to explicitly call window.Tingg.close() after any business logic.

NOTE: window.Tingg.close() can be called anywhere & at any time you wish to close the modal in your custom pages, components & widgets.

onSuccess(data) function

This function is called when the payment has been fully paid.

onFailed(data) function

This function is called when the checkout request expires without it being fully paid.

Both onSuccess and onFailed receive a single parameter data with the follow fields:

{
    "request_status_code": "178",
    "merchant_transaction_id": "skt3hf-3000.csb.app358",
    "checkout_request_id": 235815,
    "service_code": "JOHNDOEONLINE",
    "account_number": "skt3hf",
    "currency_code": "KES",
    "request_amount": "100",
    "amount_paid": "100.00",
    "payments": '[
        {
          "id": 48019,
          "msisdn": 254700000000,
          "payment_option_transaction_id": "25bb34d4-b4ad-40ae-aa1f-be0909eb2dbb",
          "account_number": "skt3hf",
          "customer_name": "Customer",
          "amount_paid": 100,
          "gateway_transaction_id": "542246309118099456",
          "date_payment_received": "2024-02-05 10:33:16",
          "gateway_overall_status": 139,
          "currency_id": "70",
          "country_id": "117",
          "service_id": "161",
          "payer_narration": "Simulate payment",
          "checkout_request_id": 235815,
          "merchant_receipt": "",
          "receiver_narration": "",
          "date_payment_acknowledged": null,
          "created_at": "2024-02-05 07:33:17",
          "payment_option_id": 1
        }
    ]',
    "failed_payments": "[]",
    "request_date": "2024-02-05 07:32:08",
    "payment_status_description": "Request fully paid",
    "msisdn": 2547000000000,
    "customer_email": "[email protected]",
    "request_description": "",
    "type": "success"
}
FieldTypeDescription
request_status_codestring|numberOverall request code indicating the status of the request
merchant_transaction_idstringThe unique merchant reference for the request you raised for the request as provided in the checkout payload
checkout_request_idstring|numberA unique identifier on Tingg’s end.
service_codestringUnique Tingg code identifying the service the payment request was raised for
account_numberstringThe reference the customer was paying for as provided in the checkout payload
currency_codestringISO Currency code of the payment made
request_amountstring|numberThe converted amount for the request raised by the merchant
amount_paidstring|numberAmount the customer paid for the request
paymentsarrayAn array of successful payments made to the request
failed_paymentsarrayAn array of failed payments made to the request
request_datestringDate when the request was raised in
payment_status_descriptionstringDescription of the status given back on the overall payment
msisdnstringThe mobile number the person came with from the merchant site
customer_emailstringCustomer's email address.
request_descriptionstringShows the description of the item being purchased.
typestringsuccess or failed

CMS Plugins

WordPress Plugin

A WooCommerce plugin that allows businesses to collect from their WordPress shops / store. Read more about it on the Wordpress Plugins store

Shopify

Coming soon

Updated 7 months ago