Query Request Status

POST https://developer.tingg.africa/checkout/v2/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 status indicating the result of payment processing. 200 - Request processed successfully. 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 - The checkout request posted was not valid JSON. 1014 - Missing `merchantTransactionID`. 1015 - Missing `checkoutRequestID`.
statusDescription	`string`	A description of the status provided above.
checkoutRequestID	`in 1013teger`	Unique transaction ID identifying the transaction as provided by the Tingg checkout platform.
merchantTransactionID	`string`	Unique transaction ID identifying the transaction as given by the merchant.
requestStatusCode	`integer`	Status of the payment received. 99 - A failed payment has been received for this request. Request is still open to receive payments. 129 - Request has expired with no partial payment received. 130 - New request raised by the merchant. 176 - Partial payment made for the request and has been marked as closed. Available for merchants who accept partial payments for their request 177 - partially paid requests pending customer to complete payment 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. 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. 188 - The payment was received by the merchant. An accept/reject call will be initiated later by merchant.
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 name offered by the merchant
accountNumber	`string`	An identifier for the account being paid for as posted in the checkout request step.
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
redirectTrigger	`string`	This indicates the trigger that necessitated a redirect to the pending or failed redirect URL. The triggers can either be: TIME - This indicate the time limit for the session has reached. USER - Customer clicked the “Back to merchant” button to be taken to customer page
shortUrl	`string`	A short URL that redirects to the express checkout that may be used to retrieve the request.
payments	`JSON array`	A list of individual payments made for the checkout request. Details of what is contained in a payment payload are given below
failedPayments	`JSON array`	A list of individual payments that may have been attempted for the checkout request but failed
rejectedPayments	`JSON 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`	An indication on whether or not transaction can be paid offline.
customerNationalID	`string`	National ID for the customer
customerPassportNumber	`string`	Passport number for the customer

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
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,
        "session": "",
        "redirectURL": "",
        "shortUrl": "",
        "redirectTrigger": "",
        "payments": [
            {
                "payerTransactionID": "dev-test-1597903771",
                "MSISDN": 254726806777,
                "accountNumber": "acc_4148655",
                "customerName": "Customer",
                "amountPaid": 6618,
                "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": [],
        "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
}