Home
Guides
Login

Redirect (Full page)

Suggest Edits

The redirect payment experience is the popular means to use Express checkout due to its simplicity.

Customers will be redirected away from their current view to a page that looks like the screenshot below, to complete their payment.

A complete checkout redirect example has been provided below in a simple HTML script that can be adopted in virtually any web application and be guaranteed to work.

<!DOCTYPE html>
<html>
  <head>
    <title>Title of the document</title>
  </head>
  <body>
    <main>
      <button id="pay-button" onclick="createCheckoutRequest()">
      PAY NOW!
      </button>
    </main>
    <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.location.replace(data.short_url);
           }) 
       }
    </script>
  </body>
</html>

Success redirect

👍

success_redirect_url

Once they successfully make a full payment they will be redirected to the success_redirect_url URL given in the checkout payload.

The redirect to the success_redirect_url is done using a FORM POST request with the parameters below:

HTTP POST Request Body

Parameter NameTypeDescription
checkout_request_idDoubleA unique identifier on Cellulant’s end.
merchant_transaction_idStringUnique ID the merchant raised for the request
request_amountDoubleThe converted amount for the request raised by the merchant
original_request_amountDoubleThe original request amount raised by the merchant in the invoice currency
request_currency_codeStringConverted currency for the request the customer made the payment in
original_request_currency_codeStringISO Code of the currency code the merchant raised the request in
account_numberDoubleMerchant reference the customer was paying for
currency_codeStringISO Currency code of the payment made
amount_paidDoubleAmount the customer paid for the request
service_charge_amountDoubleCharges added to the service for the request initiated
request_dateDateDate when the request was raised in
service_codeStringUnique service code identifying the service the payment request was raised for.
request_status_codeStringOverall request code indicating the status of the service
177 - partially paid requests
178 - indicating the request was fully paid for
179 - indicating the request was partially paid for but expired
129 - Request expired without payments
102 - Insufficient funds
101 - Invalid pin/canceled
99 - Generic Failed Payment Status
request_status_descriptionStringDescription of the status given back on the webhook request
MSISDNStringThe mobile number the person came with from the merchant site
paymentsJSON ArrayAn array of successful payments made to the request
failed_paymentsJSON ArrayAn array of any payments initiated but not successfully authorized
extra_dataStringmetadata
country_abbrvStringAbbreviation of the country

Payments array for both failed and successful payments array.

Parameter NameTypeDescription
customer_namestringCustomer name of the person who made the payment
account_numberstringMerchant reference the customer was paying for.
cpg_transaction_idStringUnique Cellulant identity
currency_codestringISO Currency code of the payment made
payer_client_codestringPayment option customer paid with e.g. Airtel
payer_client_nameStringPayment option customer name
amount_paiddoubleAmount customer paid for
service_codeStringCode of service paid to
date_payment_receivedDateWhen the payment was made and received
MSISDNstringThe mobile number the customer is paying for
payer_transaction_idstringUnique ID the MNO or bank generated for the transaction
hub_overall_statusstringThe overall status of the payment made is described on the status code table below
payer_narrationStringPayment description is given by MNO, bank, or card acquirer.

Here is a sample JSON request body that you'll receive in the IPN:

{
  "request_status_code": 178,
  "account_number": "11800",
  "merchant_transaction_id": "56679792",
  "amount_paid": 15,
  "service_charge_amount": 0,
  "request_amount": "10",
  "payments": [
    {
      "account_number": "11800",
      "payer_client_name": "Mula Checkout",
      "amount_paid": 5,
      "payer_narration": "The service request is processed successfully.",
      "date_payment_received": "2021-11-26 14:47:45.0",
      "currency_code": "KES",
      "payer_transaction_id": "PKQ082LB08",
      "cpg_transaction_id": "1195072932",
      "payer_client_code": "MULACHECKOUT_KEN",
      "hub_overall_status": 139,
      "service_code": "MULACHECKOUTONLINE",
      "customer_name": "Customer",
      "msisdn": 254700000000
    },
    {
      "account_number": "11800",
      "payer_client_name": "Mula Checkout",
      "amount_paid": 5,
      "payer_narration": "The service request is processed successfully.",
      "date_payment_received": "2021-11-26 14:47:45.0",
      "currency_code": "KES",
      "payer_transaction_id": "PKQ082LB08",
      "cpg_transaction_id": "1195072932",
      "payer_client_code": "MULACHECKOUT_KEN",
      "hub_overall_status": 139,
      "service_code": "MULACHECKOUTONLINE",
      "customer_name": "Customer",
      "msisdn": 254700000000
    },
  ],
  "original_request_amount": 10,
  "checkout_request_id": 6,
  "currency_code": "KES",
  "failed_payments": [],
  "request_currency_code": "KES",
  "request_date": "Fri Nov 26 11:47:04 GMT 2021",
  "service_code": "MULACHECKOUTONLINE",
  "request_status_description": "Success payment",
  "original_request_currency_code": "KES",
  "msisdn": "254700000000",
	"extra_data": "abcd",
	"country_abbrv": "KEN"
}

Failed redirect

❗️

fail_redirect_url

In case they re-open the link past the due_date and the checkout request is mark as expired, they will be sent to the fail_redirect_url specified in the checkout payload.

Updated 6 months ago