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:

Log the checkout request on the checkout platform that will be used for subsequent processing of charge requests, payment receipt, payment acknowledgments and refunds.
(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.
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_numberStringYesMerchant's invoice number.
merchant_transaction_idStringYesUnique Id the merchant raised for the request
raise_invoicebooleanYesFlag to raise an invoice eg. true or false
request_amountDoubleYesAmount you wish to start collecting for.
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

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": "ACCNO02561",
    "callback_url": "",
    "country_code": "KEN",
    "currency_code": "KES",
    "customer_email": "[email protected]",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "due_date": "2021-11-05 20:00:00",
    "fail_redirect_url": "",
    "invoice_number": "1234",
    "merchant_transaction_id": "787867001614",
    "raise_invoice": false,
    "request_amount": 100,
    "request_description": "Bag",
    "service_code": "JOHNDOEONLINESERVICE",
    "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!