Post Checkout and Charge Request

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

This step combines both step 2. and step 3 and is useful when the payment option (payerModeID) is predefined by the merchant.

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
currencyCode	`string`	The currency the amount passed is in	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
payerModeID	`integer`	This is a number representing the payment option client and the mode in use e.g. using a mobile money client paying via STK push. This will be provided as part of the payment options	TRUE
paymentWebhookUrl	`string`	A server to server URL endpoint that will be called to notify a merchant of a complete payment.	TRUE
languageCode	`string`	This is a two digit code in which the available instructions will be provided.	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",
    "payerModeID": "",
  	"languageCode":"en",
    "extraData": {
      "bundleID": "30GB"
     }
}

Response Parameters

Parameter Name	Type	Description
statusCode	`integer`	Request status code. 200 - Checkout request status fetched successfully from the checkout platforms 500 - Generic failure occurred. Could be as a result of a system failure on the checkout platform 1007 - Missing `countryCode`. 1013 - The checkout request posted was not valid JSON 1014 - Missing `merchantTransactionID`. 1015 - Missing `checkoutRequestID`. 1017 - Invalid charge `MSISDN` provided. 1019 - Missing or invalid `customerEmail` 1020 - Missing `dueDate` 1027 - Invalid amount provided. The `chargeAmount` should be between the minimum and maximum amounts provided for the payment option.
statusDescription	`string`	Description of the transaction status.
checkoutRequestID	`integer`	The unique request identifying the transaction logged in the checkout platform.
merchantTransactionID	`string`	The unique transaction ID from merchant's system identifying the request.
chargeRequestID	`integer`	A unique identifier for the charge request as stored on our database.
paymentInstructions	`string`	Instructions to provide to the customer on how to make a payment.
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.
chargeResults	`string`	Containing details of the results of the request being processed.
languageCode	`string`	A two letter code representing the language that the instructions are in.
chargeMsisdn	`integer`	The charge mobile number provided earlier in the request.
chargeAmount	`integer`	The charge amount as was provided earlier in the request.
chargeRequestDate	`string`	The date and time in which the charge request was logged. This will be in UTC time.
paymentRedirectUrl	`string`	The redirect link given for the payment option selected if no redirect is required the value will be null or empty

Example

Successful Response

{
    "status": {
        "statusCode": 200,
        "statusDescription": "Successfully processed request"
    },
    "results": {
        "checkoutRequestID": 106671790,
        "merchantTransactionID": "798879913",
        "conversionRate": 1,
        "originalCurrencyCode": "XOF",
        "requestAmount": 200,
        "convertedCurrencyCode": "XOF",
        "convertedAmount": 200,
        "paymentOptions": [
            {
                "paymentModeName": "Push Notification",
                "paymentModeID": 3,
                "serviceCode": "TEST",
                "payerClientName": "MTN MTN_CI",
                "payerModeID": 672,
                "paymentOptionCode": "Mobile Money",
                "payerClientCode": "MTN_CI",
                "countryCode": "CI",
                "clientLogo": "INTECHMTN_22-Jun-2023_1687438133.png",
                "serviceName": "Glovo",
                "minChargeAmount": 200,
                "maxChargeAmount": 1500000,
                "currencyCode": "XOF",
                "paymentInstructions": "You will receive a prompt on your mobile number ^CHARGE_MSISDN^. Enter your PIN to authorize your payment of XOF ^CHARGE_AMOUNT^ for reference ^ACCOUNT_NUMBER^",
                "languageCode": "en"
            },
            {
                "paymentModeName": "Push Notification",
                "paymentModeID": 3,
                "serviceCode": "TEST",
                "payerClientName": "Moov MOOV_CI",
                "payerModeID": 671,
                "paymentOptionCode": "Mobile Money",
                "payerClientCode": "MOOV_CI",
                "countryCode": "CI",
                "clientLogo": "INTECHMOOV_22-Jun-2023_1687438405.png",
                "serviceName": "Glovo",
                "minChargeAmount": 200,
                "maxChargeAmount": 1500000,
                "currencyCode": "XOF",
                "paymentInstructions": "You will receive a prompt on your mobile number ^CHARGE_MSISDN^. Enter your PIN to authorize your payment of XOF ^CHARGE_AMOUNT^ for reference ^ACCOUNT_NUMBER^",
                "languageCode": "en"
            },
            {
                "paymentModeName": "Voucher Validation",
                "paymentModeID": 12,
                "serviceCode": "TEST",
                "payerClientName": "Orange ORANGE_CI",
                "payerModeID": 673,
                "paymentOptionCode": "Mobile Money",
                "payerClientCode": "ORANGE_CI",
                "countryCode": "CI",
                "clientLogo": "INTECHORANGE_22-Jun-2023_1687437960.png",
                "serviceName": "Glovo",
                "minChargeAmount": 200,
                "maxChargeAmount": 150000000,
                "currencyCode": "XOF",
                "paymentInstructions": "<p>Dial <b>#144*82#</b> using your mobile number <b>^CHARGE_MSISDN^</b> to receive a voucher/O.T.P. </p><p>Enter the code in the input field below to proceed with your payment of XOF ^CHARGE_AMOUNT^ for reference ^ACCOUNT_NUMBER^<p>",
                "languageCode": "en"
            },
            {
                "paymentModeName": "External processing With Redirect",
                "paymentModeID": 26,
                "serviceCode": "TEST",
                "payerClientName": "Wave Ivory Coast",
                "payerModeID": 707,
                "paymentOptionCode": "Mobile Money",
                "payerClientCode": "WAVECI",
                "countryCode": "CI",
                "clientLogo": "37a54f9d-885a-420e-8cc5-1dd76816aa94.png",
                "serviceName": "Glovo",
                "minChargeAmount": 1,
                "maxChargeAmount": 100000000,
                "currencyCode": "XOF",
                "paymentInstructions": "External processing With Redirect",
                "languageCode": "en"
            }
        ],
        "chargeResults": {
            "chargeRequestDate": "2024-12-06 14:15:21",
            "chargeRequestID": 79433556,
            "channelRequestID": null,
            "checkoutRequestID": 106671790,
            "merchantTransactionID": "798879913",
            "chargeAmount": 200,
            "chargeMsisdn": 2250789588760,
            "paymentInstructions": "External processing With Redirect",
            "languageCode": "en",
            "routingResponse": {
                "url": "https://pay.wave.com/c/cos-1t8kzyb5g207j?a=200&c=XOF&m=CELLULANT%20%2A%20Into",
                "method": "GET",
                "requestType": "form_get",
                "headers": [
                    "application/x-www-form-urlencoded"
                ],
                "postParams": [],
                "paymentRedirectUrl": "https://pay.wave.com/c/cos-1t8kzyb5g207j?a=200&c=XOF&m=CELLULANT%20%2A%20Into"
            },
            "thirdPartyResponse": {
                "tinggVirtualAccountID": null,
                "tinggAccount": null,
                "tinggBank": "Wave Ivory Coast",
                "tinggName": "Wave Ivory Coast"
            },
            "paymentRedirectUrl": "https://pay.wave.com/c/cos-1t8kzyb5g207j?a=200&c=XOF&m=CELLULANT%20%2A%20Into"
        }
    }
}

Failure Response

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

Authentication Failure Response

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