Initiate checkout request

This function is used to initiate a checkout request after the customer has provided information about the product or service they wish to acquire.

The initiate checkout request function will process the request as follows:

  1. Log the checkout request on the checkout platform that will be used for subsequent processing of charge requests, payment receipt, payment acknowledgments and refunds.
  2. (Optional) Raise an invoice and send a message to customer (SMS/email) that will contain a link to access the checkout request logged by merchant.
  3. Log merchant callback details i.e. payment web-hook URL in which an instant payment notification will be posted to.


Live Endpoint

Request Parameters

KeyValue TypeRequiredDescription
msisdnStringYesMobile number for the customer.
account_numberStringYesAccount number for the customer on the merchant system. This is the reference the customer will pay to.
callback_urlStringYesString of the endpoint we are to send the webhook request to.
country_codeStringYes3 digit ISO code of the country you wish to collect payment for
currency_codeStringYes3 digit ISO code of the currency the merchant is invoicing for.
customer_emailStringYesCustomer email the customer wished to pay for.
customer_first_nameStringYesCustomer first name
customer_last_nameStringYesCustomer last name
due_dateStringYesDate when the request expires in UTC.Date format is YYYY-MM-DD HH:mm:ss
payment_option_codeStringNoPayment option code of the payment options the merchant wishes to collect for
fail_redirect_urlStringYesWhere we will redirect the customer to when the payment time passed above expires.
invoice_numberStringNoMerchant's invoice number.
merchant_transaction_idStringYesUnique Id the merchant raised for the request
raise_invoicebooleanNoFlag to raise an invoice eg. true or false
request_amountDoubleYesAmount you wish to start collecting for.
national_idStringNoThe customers country identification issued by the local authority
passport_numberStringNoThis is the customer's issued passport identification number as indicated in the passport.
request_descriptionStringYesShows the description of the item being purchased.
service_codeStringYesThe service code assigned to the merchant on the tingg portal
success_redirect_urlStringYesWhere we will redirect the customer to after a successful payment is made.
charge_beneficiariesJSONArrayNoExtra charge client we should settle to

charge_beneficiaries JSONArray elements if included:

KeyValue TypeRequiredDescription
charge_beneficiary_codeStringYesThis is the client who we are to settle to on behalf of the customer.
amountDoubleYesAmount we should settle the service provider above
    "msisdn": 254700000000,
    "account_number": "TinggAcc01",
    "callback_url": "",
    "country_code": "KEN",
    "currency_code": "KES",
    "customer_email": "[email protected]",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "due_date": "2024-03-30 20:00:00",
    "fail_redirect_url": "",
    "merchant_transaction_id": "787867001614",
    "raise_invoice": false,
    "request_amount": 100,
    "request_description": "Bag",
    "service_code": "TINGGTEST",
    "success_redirect_url": ""

Response Status Codes

Status CodeDescription
200Success. Checkout request successfully logged in the checkout platform.
500Failure. Generic failure occurred. Could be as a result of a system failure on the checkout platform.
1001No request found.
1007Missing country code. The checkout request posted was missing a country_code
1013Not JSON. The checkout request posted was not valid JSON
1014Missing merchant transaction id. The request did not have a merchant_transaction_id
1015Missing checkout request id.The request did not have a checkout_request_id
1017Invalid charge msisdn provided. The charge_msisdn provided was not valid in the country provided
1027Invalid amount provided. The charge_amount should be between the minimum and maximum amounts provided for the payment option.
Click Try It! to start a request and see the response here!