Home
Guides
Login

Modal (pop-up)

Suggest Edits

The following steps provide a guide on how to seamlessly integrate Tingg Checkout into your website or online store.

The modal experience that will render a pop-up on top of your web page, meaning the customer does not have to leave your website to make a payment.

The customer will be presented with the payment options configured by the merchant as shown below. The payment options are divided into three main categories; mobile money, and mobile banking & card. Activate your payment options in your sandbox account under the 'Payment Options' tab.

Try Demo

👍

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

Add CDN

You'll need to add a JavaScript tag of the CDN link to add to your site.

Here is the src URL https://cdn.cellulant.africa/js/tingg-checkout-library.js. Use it as you would wish in the language or framework you are working with.

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

import "./globals.css";
import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        {children}
        <script async src="https://cdn.cellulant.africa/js/tingg-checkout-library.js"></script>
      </body>
    </html>
  );
}

The script will add a Tingg object on the window object. Accessing window.Tingg exposes some APIs used to render the Express checkout UI.

Usage

After the CDN has been included, add a call to action 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. Encrypt the checkout payload in 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(function (resp) {
           	 return resp.json()
         	})
           .then(function (data) {
           		window.Tingg.renderCheckout({            
                 environment: "sandbox",
                 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

Updated 9 months ago