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
https://api.tingg.africa/v3/checkout-api/checkout/request

Request Parameters

Key	Value Type	Required	Description
`msisdn`	String	Yes	Mobile number for the customer.
`account_number`	String	Yes	Account number for the customer on the merchant system. This is the reference the customer will pay to.
`callback_url`	String	Yes	String of the endpoint we are to send the webhook request to.
`country_code`	String	Yes	3 digit ISO code of the country you wish to collect payment for
`currency_code`	String	Yes	3 digit ISO code of the currency the merchant is invoicing for.
`customer_email`	String	Yes	Customer email the customer wished to pay for.
`customer_first_name`	String	Yes	Customer first name
`customer_last_name`	String	Yes	Customer last name
`due_date`	String	Yes	Date when the request expires in UTC.Date format is YYYY-MM-DD HH:mm:ss
`payment_option_code`	String	No	Payment option code of the payment options the merchant wishes to collect for
`fail_redirect_url`	String	Yes	Where we will redirect the customer to when the payment time passed above expires.
`invoice_number`	String	No	Merchant's invoice number.
`merchant_transaction_id`	String	Yes	Unique Id the merchant raised for the request
`raise_invoice`	boolean	No	Flag to raise an invoice eg. true or false
`request_amount`	Double	Yes	Amount you wish to start collecting for.
`national_id`	String	No	The customers country identification issued by the local authority
`passport_number`	String	No	This is the customer's issued passport identification number as indicated in the passport.
`request_description`	String	Yes	Shows the description of the item being purchased.
`service_code`	String	Yes	The service code assigned to the merchant on the tingg portal
`success_redirect_url`	String	Yes	Where we will redirect the customer to after a successful payment is made.
charge_beneficiaries	JSONArray	No	Extra charge client we should settle to

charge_beneficiaries JSONArray elements if included:

Key	Value Type	Required	Description
`charge_beneficiary_code`	String	Yes	This is the client who we are to settle to on behalf of the customer.
`amount`	Double	Yes	Amount we should settle the service provider above

{
    "msisdn": 254700000000,
    "account_number": "TinggAcc01",
    "callback_url": "https://jsonplaceholder.typicode.com/todos/1",
    "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": "https://jsonplaceholder.typicode.com/todos/1",
    "merchant_transaction_id": "787867001614",
    "raise_invoice": false,
    "request_amount": 100,
    "request_description": "Bag",
    "service_code": "TINGGTEST",
    "success_redirect_url": "https://jsonplaceholder.typicode.com/todos/1"
}

Response Status Codes

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

📘Live Endpoint

Request Parameters

Response Status Codes

📘
Live Endpoint