2. Post Checkout Request

POST https://developer.tingg.africa/checkout/v2/custom/requests/initiate

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

Log the checkout request on the checkout platform that will be used for subsequent processing of charges 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.

📘
NOTE:
The POST checkout request function is necessary to retrieve the list of payment options configured for the service.

Header Parameters

Header	Value	Required
Authorization	`Bearer <Bearer_Token>` generated during authenticate request in step 1.	YES
Content-Type	`application/json`	YES

Request Parameters

Parameter Name	Type	Description	Required
merchantTransactionID	`string`	Unique identifier of the request for payment	TRUE
currencyCode	`string`	Currency of the amount to be collected	TRUE
requestAmount	`double`	Merchant amount to be collected.	TRUE
countryCode	`string`	The ISO 3166-1 alpha-2 code of the country you wish to collect payment for. The country code ensures we present valid payment options available in that particular country.	TRUE
accountNumber	`string`	A unique reference number identifying the customer's account	TRUE
serviceCode	`string`	Merchant's service code. This can be found here.	TRUE
dueDate	`string`	Time window a customer should complete making a payment. If not passed passed time defaults to 12 hours. Date format is `YYYY-MM-DD hh:mm:ss`.	TRUE
requestDescription	`string`	Shows the description of the item being purchased.	FALSE
customerFirstName	`string`	Customer first name	FALSE
customerLastName	`string`	Customer last name	FALSE
MSISDN	`string`	Customer's phone number formatted as given in the E.164 phone numbering.	TRUE
customerEmail	`string`	Customer email	FALSE
paymentWebhookUrl	`string`	A server to server URL endpoint that will be called to notify a merchant of a complete payment.	TRUE
successRedirectUrl	`string`	The URL where the customer will be redirected on merchant's site once a full payment is made.	TRUE
failRedirectUrl	`string`	URL where the customer will be redirected to if a full payment is not done within the payment window.	TRUE
extraData	`JSON`	Additional data specific to a client's application	FALSE

Example

{
    "merchantTransactionID" : "<unique_transaction_id>",
    "requestAmount" : 100.50,
    "currencyCode" : "KES",
    "accountNumber" : "ACC12345",
    "serviceCode" : "TESTSERVICE",
    "dueDate" : "0000-00-00 00:00:00",
    "requestDescription" : "Getting service/good x",
    "countryCode" : "KE",
    "customerFirstName" :"John",
    "customerLastName" : "Smith",
    "MSISDN" : "<valid_mobile_number>",
    "customerEmail" : "[email protected]",
    "paymentWebhookUrl" : "https://my.url.com/webhook/receive",
    "successRedirectUrl" : "<YOUR_SUCCESS_REDIRECT_URL>",
    "failRedirectUrl" : "<YOUR_FAIL_REDIRECT_URL>",
    "extraData": {
      "bundleID": "30GB"
    }
}

Response Parameters

Parameter Name	Type	Description
statusCode	`integer`	Request status code. See full status code details below. 200 - Checkout request status fetched successfully from the checkout platform 500 - Generic failure occurred. Could be as a result of a system failure on the checkout platform 1003 - The `serviceCode` sent in the checkout request did not match any the checkout platform service 1004 - Duplicate request. A similar checkout request already exists in the checkout platform. Could be as a result of re-posting a checkout request or re-using a merchantTransactionID. 1006 - The checkout request posted was missing a `languageCode` 1007 - The checkout request posted was missing a `countryCode` 1012 - The checkout request posted had an invalid `callbackURL` 1013 - The checkout request posted was not valid JSON 1014 - Missing `merchantTransactionID`. 1017 - Missing `serviceCode`. 1018 - Missing `MSISDN`. 1019 - Invalid `MSISDN`. 1025 - Missing `currencyCode`. 1026 - Missing `amount`. 1027 - Invalid `amount` 1028 - Missing `accountNumber`.
statusDescription	`string`	Description of the transaction status.
checkoutRequestID	`integer`	Unique request ID identifying the transaction provided by the checkout platform.
merchantRequestID	`string`	Transaction ID as given by the merchant identifying the transaction.
originalCurrencyCode	`string`	A 3 digit ISO code for the original currency of the amount. This will be as provided by the merchant.
convertedCurrencyCode	`string`	A 3 digit ISO code for the converted currency of the amount. This will be different of the service in use supports a different currency from the one provided in the request
requestAmount	`double`	Request amount that was provided by the merchant.
convertedAmount	`double`	Converted amount that will be billed in the local currency. This is a multiplication of the original amount time and the conversion rate available
conversionRate	`double`	The rate of conversion available when the provided currency is converted into the working currency
paymentOptions	`JSON Array`	A list of payment options available for the service selected. More information on the option parameters can be found under Fetch Payment Options.

Examples

Successful Response:

{
    "status": {
        "statusCode": 200,
        "statusDescription": "Successfully processed request"
    },
    "results": {
        "checkoutRequestID": 407073,
        "merchantTransactionID": "MTX437913",
        "conversionRate": 1,
        "originalCurrencyCode": "KES",
        "requestAmount": 6207,
        "convertedCurrencyCode": "KES",
        "convertedAmount": 6207,
        "paymentOptions": [
            {
                "paymentModeName": "USSD Push",
                "paymentModeID": 3,
                "serviceCode": "TESTSERVICE",
                "payerClientName": "Safaricom Limited",
                "payerModeID": 1,
                "paymentOptionCode": "Mobile Money",
                "payerClientCode": "SAFKE",
                "countryCode": "KE",
                "clientLogo": "Safaricom_Limited_10-Oct-2017_1507650496.png",
                "serviceName": "Test Service",
                "minChargeAmount": 1,
                "maxChargeAmount": 70000,
                "currencyCode": "KES",
                "paymentInstructions": "<p>You will receive a prompt on mobile number <b>^CHARGE_MSISDN^</b>.<br/> Enter your M-Pesa PIN to authorize your payment of <b>KES ^CHARGE_AMOUNT^</b> to account number <b>^ACCOUNT_NUMBER^</b>. </p>",
                "languageCode": "en"
            },
        ]
    }
}

Failure Response:

{
    "status": {
        "statusCode": 1014,
        "statusDescription": "The merchant transaction id field is required."
    },
    "results": null
}

Authentication Failure Response:

{
    "message": "Unauthenticated.",
    "status_code": 500
}

📘NOTE:

Header Parameters

Request Parameters

Response Parameters

📘
NOTE: