4. Acknowledge Payment

https://developer.tingg.africa/checkout/v2/custom/requests/acknowledge

At this moment the merchant has received the payments on their end by either fetching the request details using query result status or through the callback invocation on the paymentWebhookUrl. The acknowledgment can only be done on a request that is fully paid and is not yet acknowledged.

The post acknowledgement request does the following:

Changes the status of the requests to the one provided by the merchant.
Updates all the payments of the corresponding request to the status provided by the merchant. This may result in more actions e.g. reversal of rejected payment to customer or settlement of accepted payment.

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
checkoutRequestID	`integer`	Unique transaction ID identifying the transaction as provided by the checkout platform.	TRUE
merchantTransactionID	`string`	Unique transaction ID identifying the transaction as given by the merchant.	TRUE
statusCode	`integer`	A status indicating the result of payment processing. 180 - The payment(s) for the request was rejected by the merchant 183 - The payment(s) for the request was accepted by the merchant 188 - The payment was received by the merchant. An accept/reject call will be initiated later.	TRUE
statusDescription	`string`	A description of the status provided above.	TRUE
receiptNumber	`integer`	A transaction ID indicating the receipt of the payments.	TRUE
currenctCode	`string`	Acknowledgment currency code. This should be in the original billing currency or the currency that the payment was collected in.	FALSE
acknowledgeAmount	`double`	Amount to acknowledge for this request.	FALSE

Example

{
   "merchantTransactionID":"MTX50477520",
   "checkoutRequestID":4459156,
   "receiptNumber":"receipt-id_5241435" ,
   "statusCode":183,
   "statusDescription":"Accepted payment"
}

Response Parameters

Parameter Name	Type	Description
statusCode	`integer`	A status indicating the result of payment processing. 200 - Acknowledgement done successfully. 500 - Generic failure occurred. Could be as a result of a system failure on the Tingg checkout platform. 1001 - No payment available for acknowledgement. Payment might also have been acknowledged. 1013 - The checkout request posted was not valid JSON. 1014 - Missing `merchantTransactionID`. 1015 - Missing `checkoutRequestID`. 1032 - Missing `statusDescription`.
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
payments	`JSON Array`	An array of the payments made.

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

Parameter Name	Type	Description
paymentID	`integer`	Unique payment reference on the Cellulant Payment Gateway
checkoutRequestID	`integer`	Unique transaction ID identifying the transaction as provided by the Tingg checkout platform.
cpgTransactionID	`integer`	Unique transaction id on the Cellulant Payment Gateway
payerTransactionID	`string`	Unique payment reference provided by the payment option ie MPESA reference
MSISDN	`string`	Mobile number used to complete the payment
accountNumber	`string`	Reference presented to complete a payment
customerName	`string`	Customer names. NB: Provided only when available
amountPaid	`double`	Amount paid / authorized by the customer
merchantReceipt	`string`	Receipt number provided during payment acknowledgment
payerNarration	`string`	Description of payment provided by the payment option
receiverNarration	`string`	Description of payment provided by merchant on acknowledgment
hubOverallStatus	`integer`	Payment status on the Cellulant Payment Gateway
statusCodeDesc	`string`	Description of the hubOverallStatus
currencyID	`integer`	Unique currency ID as provided on Tingg checkout platform
payerClientCode	`string`	Unique code of the payment option on the Tingg checkout platform
payerClientName	`string`	The name provided for the payment option on the Tingg checkout platform
payerClientDisplayName	`string`	The name of the payment display on checkout when the option is selected on the Tingg checkout platform
ownerClientCode	`string`	Unique merchant code on the Tingg checkout platform
ownerClientName	`string`	Merchants name on the Tingg checkout platform
ownerClientDisplayName	`string`	Merchants display name on the Tingg checkout platform
merchantTransactionID	`string`	Unique transaction ID identifying the transaction as given by the merchant.
convertedAmount	`double`	Amount converted to the currency of collection in the given country
totalPayableAmount	`double`	Amount to be paid by the customer on the Tingg checkout platform
datePaymentReceived	`string`	Date when the payment was completed by the customer
datePaymentAcknowledged	`string`	Date when the payment was acknowledged by the customer on the Tingg checkout platform
dateCreated	`string`	Date when the payment was recorded on the Tingg checkout platform
currencyCode	`string`	Currency code which the customer was charged in by the payment option
countryCode	`string`	Country ISO Code where payment was collected

Example

Successful Response

{
    "status": {
        "statusCode": 200,
        "statusDescription": "Acknowledged successfully"
    },
    "results": {
        "checkoutRequestID": 406287,
        "merchantTransactionID": "MTX4148655",
        "requestStatusCode": 183,
        "payments": [
            {
                "paymentID": 2760738,
                "checkoutRequestID": 406287,
                "cpgTransactionID": "10776883",
                "payerTransactionID": "dev-test-1610708451",
                "MSISDN": 254722100200,
                "accountNumber": "test",
                "customerName": "Customer",
                "amountPaid": 10,
                "merchantReceipt": "receipt-id_1680382",
                "payerNarration": null,
                "receiverNarration": "Accepted test payment",
                "hubOverallStatus": 139,
                "statusCodeDesc": "New Payment",
                "currencyID": 70,
                "payerClientCode": "SAFKE",
                "payerClientName": "Safaricom Limited",
                "ownerClientCode": "DEV3411",
                "ownerClientName": "Dev Client",
                "ownerClientDisplayName": "ohmzi",
                "merchantTransactionID": "id_1680382",
                "convertedAmount": 10,
                "totalPayableAmount": 10,
                "datePaymentReceived": "2021-01-15 14:00:58",
                "datePaymentAcknowledged": null,
                "dateCreated": "2021-01-15 14:00:59",
                "currencyCode": "KES",
                "countryCode": "KE"
            }
    }
}

Failure Response

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

Failed Response: Acknowledging already processed payment

{
    "status": {
        "statusCode": 1001,
        "statusDescription": "Data not found"
    },
    "results": null
}

Authentication Failure Response

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