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