4. Query Request Status

POST https://checkout.tingg.africa/checkout-translation-service/custom/requests/query-status

This function is a subset of the callback functionality, where a payment is sent to the merchants callback, and can be used to prematurely query for the status i.e. check for request status before the full payment is done.

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`	The unique transaction ID from the merchant's system identifying the request that was previously initiated on the post checkout request step.	TRUE
serviceCode	`string`	Merchant's service code. This can be found here.	TRUE
checkoutRequestID	`string`	A unique transaction ID identifying the transaction logged in the checkout platform	FALSE

Example

{
	"merchantTransactionID":"id_4148655",
	"serviceCode":"<YOUR_SERVICE_CODE>",
	"checkoutRequestID":""
}

Response Parameters

`Parameter Name`	`Type`	`Description`
statusCode	integer	A code providing information about the processing status of the request. See a full list of the status codes with descriptions below. 200 - Success. 500 - Generic failure occurred. Could be as a result of a system failure on the Tingg checkout platform. 1001 - No checkout request found matching the details. 1013 - Not JSON. The checkout request posted was not valid JSON. 1014 - Missing merchant transaction ID. The request did not have a merchantTransactionID. 1015 - Missing checkout request ID.The request did not have a checkoutRequestID.
statusDescription	string	More information regarding the status of processing.
checkoutRequestID	long	The unique request identifying the transaction logged in the checkout platform
merchantTransactionID	string	The unique transaction ID from merchant's system identifying the request
requestStatusCode	integer	A code identifying the status of the request i.e paid, unpaid expired etc. A list of available status codes will be provided below 129 - Request has expired with no partial payment received. 130 - New request raised by the merchant. 177 - Partial payment made for the request. 178 - Full payment made for the request. 179 - Request has expired with one or more partial payments made. The partial payment(s) will be reversed. 180 - Request Fully paid for but acknowledged as rejected by the merchant. 183 - Request fully paid for but acknowledged as accepted by the merchant. 188 - The payment was received by the merchant. An accept/reject call will be initiated later by merchant. 184 - This is indicates that a refund of part of the request amount has been initiated. 185 - This is indicates that full refund the request amount has been initiated. 186- This is indicates that the part refund for the request was successfully processed. 187 - This is indicates that the full refund for the request was successfully processed.
MSISDN	integer	The mobile number that the checkout request was originally initiated with.
serviceCode	string	A unique code identifier for the merchant's service in use as provided on the checkout platform.
serviceName	string	Service description offered by the merchant
accountNumber	string	An identifier for the account being paid for as posted in the checkout initiation leg.
amountPaid	integer	This is the total amount paid for at the time of fetching the checkout request status. More details of the payments can be found in the payments array as will be provided below.
requestAmount	double	The amount that the merchant needed to charge the customer for items selected on their platform
paymentCurrencyCode	string	The currency code used in the transaction.
requestCurrencyCode	string	The currency code used in the transaction request.
requestDate	string	The date in which the checkout request was logged onto the checkout platform.
session	string	Session value provided for multiple payment session. Unique per merchant implementations
redirectURL	string	Redirect URL provided for a specific payment session Unique per merchant implementations
shortUrl	string	A short URL that redirects to the express checkout that may be used to retrieve the request.
payments	array	A list of individual payments made for the checkout request. Details of what is contained in a payment payload are given below
failedPayments	array	A list of individual payments that may have been attempted for the checkout request but failed
rejectedPayments	array	A list of individual payments that may have been attempted for the checkout request but were rejected
paymentInstructions	String	Instructions to provide to the customer on how to make a payment
offline	boolean	Transaction can be paid offline

The payments/failedPayments/rejectedPayments array holds a list of payments that have been made for the current request.

`Parameter Name`	`Type`	`Description`
`payerClientCode`	`string`	`Unique code of the payment option on the Tingg checkout platform`
`payerTransactionID`	`string`	`Unique payment reference provided by the payment option ie MPESA reference`
`amountPaid`	`double`	`Amount paid / authorized by the customer`
`amountPaidInOriginalCurrency`	`double`	`Amount the customer paid in original currency code (requestCurrencyCode)`
`requestCurrencyCode`	`string`	`Currency code that the merchant sent in their original request.`
`clientName`	`string`	`Name of the originating payer client.`
`MSISDN`	`string`	`Mobile number used to complete the payment`
`cpgTransactionID`	`integer`	`Unique transaction id on the Cellulant Payment Gateway`
`currencyCode`	`string`	`Currency code which the customer was charged in by the payment option`
`paymentDate`	`string`	`The date in which the payment was logged onto the Cellulant payment gateway.`
`clientCategoryID`	`integer`	`The category ID of the payment originating clients.`
`clientCategoryName`	`string`	`The category name of the payment originating clients.`
`extraData`	`string`	`Contains extra parameters based on the type of payment made.`

Examples

Successful Response

{
    "status": {
        "statusCode": 200,
        "statusDescription": "Successfully processed request"
    },
    "results": {
        "checkoutRequestID": 406287,
        "merchantTransactionID": "MTX4148655",
        "MSISDN": 25470000000,
        "accountNumber": "acc_4148655",
        "requestDate": "2020-08-20 09:08:31",
        "requestStatusCode": 183,
        "serviceName": "Test Servuce",
        "serviceCode": "Test Service",
        "requestCurrencyCode": "KES",
        "requestAmount": 6618,
        "paymentCurrencyCode": "KES",
        "amountPaid": 6618,
        "amountPaidInOriginalCurrency":6618,
        "conversionRate":1,
        "session": "",
        "redirectURL": "",
        "shortUrl": "",
        "redirectTrigger": "",
        "payments": [
            {
                "payerTransactionID": "dev-test-1597903771",
                "MSISDN": 254726806777,
                "accountNumber": "acc_4148655",
                "customerName": "Customer",
                "amountPaid": 6618,
                "amountPaidInOriginalCurrency":6618,
                "requestCurrencyCode":"KES",
                "payerClientCode": "BOA-K",
                "cpgTransactionID": "10763559",
                "paymentDate": "2020-08-20 09:09:43",
                "clientName": "Bank of Africa - Kenya",
                "clientDisplayName": "Bank of Africa",
                "currencyCode": "KES",
                "currencyID": 70,
                "paymentID": 2526723,
                "hubOverallStatus": 139,
                "clientCategoryID": 3,
                "clientCategoryName": "Banks",
                "payerNarration": null
            }
        ],
      "failedPayments": [
            {
                "payerTransactionID": "dev-test-1597903771",
                "MSISDN": 254726806777,
                "accountNumber": "acc_4148655",
                "customerName": "Customer",
                "amountPaid": 6618,
                "amountPaidInOriginalCurrency":6618,
                "requestCurrencyCode":"KES",
                "payerClientCode": "BOA-K",
                "cpgTransactionID": "10763559",
                "paymentDate": "2020-08-20 09:09:43",
                "clientName": "Bank of Africa - Kenya",
                "clientDisplayName": "Bank of Africa",
                "currencyCode": "KES",
                "currencyID": 70,
                "paymentID": 2526723,
                "hubOverallStatus": 139,
                "clientCategoryID": 3,
                "clientCategoryName": "Banks",
								"paymentStatus":"TIMEOUT",
                "payerNarration": null
            }
				],
        "rejectedPayments": [],
        "paymentInstructions": "",
        "offline": true,
        "customerNationalID": "",
        "customerPassportNumber": ""
    }
}

Failure Response

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

Authentication Failure Response

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

Failed Payment Status (Work in Progress)

Kindly note on query under the failedPayments array we will respond with the exact failed status code under paymentStatus field of why the request failed on the MNO's end. Here the overallStatus for the request will be 130 or 129 however the individual failed payment will have the correct status code with the reason for failure. Note the new field showing the actual failure reason will be under failedPayments[].paymentStatus

Status Code	Description
FAILED	Generic failure reason given by the payment provider.
TIMEOUT	There was a timeout when MNO was sending request to end users handset or customer did not enter their pin in time.
INVALID_PIN	Customer entered incorrect pin.
BLOCKED	Customers mobile number was blocked by the MNO.
INSUFFICIENT_BALANCE	This indicates customer does not have enough money in their wallet to complete these transactions.
CANCELLED	Request was cancelled by the customer.
LIMIT_EXCEEDED	Declined due to limit rule: would exceed or fall below the transfer limits
SUCCESS	Payment was debited successfully.
ERROR	Internal error / network timeout when trying to reach the MNO / Authentication error when sending the request to the MNO
NOT_ALLOWED	Customer is not allowed to make such a transaction either due to decimals or their account is on hold or it is a suspected fraudulent transaction
ENGAGED	Handset has a similar request they are processing hence cannot proceed.
INVALID	For the request sent one of the parameters are not correct and has a problem.
ACCOUNT_NOT_FOUND	MSISDN or wallet is not available on the acquirers end.