Initiate Refund

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

This request is used by merchants to initiate a refund request for a transactions that was initially accepted and a product or service was fulfilled.

This can only be used after the merchant has acknowledged the payments as accepted for a transaction in 2 ways:

Invoking the POST acknowledge endpoint.
Returning the acknowledgment status on the webhook callback response.

The initiate refunds request achieves the following:

Validates that a refund can be initiated to the customer based on the amount to refund, the payment channels that were used to make the payment and the details provided to make the refund.
Log the refund request and forward it for processing. A response will immediately be provided as to whether the validation and logging of the request was successful.

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 Tingg checkout platform.	TRUE
merchantTransactionID	`string`	Unique transaction ID identifying the transaction as given by the merchant.	TRUE
refundType	`string`	A flag indicating the type of refund to be done; can either be `full`or `partial`.	TRUE
refundAmount	`double`	The amount to be refunded. This value is optional if the refundType is `full`.	FALSE
currencyCode	`string`	A three letter ISO Code for currency the refund amount currency. If not provided, the original request currency will be used.	TRUE
narration	`string`	A reason for the refund.	FALSE
extraDetails	`string`	A JSON string to provide extra details about the refund e.g. customer bank details for some channels.	FALSE

Example

Full Refund

{
    "merchantTransactionID":"MTX5057010",
    "checkoutRequestID":"407271",
    "refundType":"full" ,
    "refundAmount":0,
    "currencyCode":"",
    "narration":"",
    "extraDetails":""
}

Partial Refund

{
    "merchantTransactionID":"MTX5057010",
    "checkoutRequestID":"407271",
    "refundType":"partial" ,
    "refundAmount":1000,
    "currencyCode":"KES",
    "narration":"Partial refund for undelivered service",
    "extraDetails":""
}

Response Parameters

Parameter Name	Type	Description
statusCode	`integer`	A status indicating the result of payment processing. 184 - Partial reversal initiated. 185 - Full reversal initiated. 186 - Partial reversal complete. 187 - Full reversal complete 200 - Refund initiated successfully. 294 - Payment pending partial reversal. 297 - Payment pending full reversal. 500 - Generic failure occurred. Could be as a result of a system failure on the Tingg checkout platform. 1001 - No payment available for refund processing 1013 - The checkout request posted was not valid JSON. 1014 - Missing `merchantTransactionID`. 1015 - Missing `checkoutRequestID`. 1040 - invalid `refundType`. 1041 - Invalid `refundAmount`
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
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
payerClientCode	`string`	Unique code of the payment option on the Tingg checkout platform
clientName	`string`	Merchants name on the Tingg checkout platform
paymentDate	`string`	Date when the payment was completed by the customer
currencyCode	`string`	Currency code which the customer was charged in by the payment option
refundAmount	`integer`	The total amount that the customer is going to pay.

Example
Successful Response

{
    "status": {
        "statusCode": 200,
        "statusDescription": "Refund initiated successfully"
    },
    "results": {
        "checkoutRequestID": "716003",
        "merchantTransactionID": "unique_transaction_id07",
        "refundAmount": 100,
        "refundCurrency": "KES",
        "payments": [
            {
                "payerTransactionID": null,
                "MSISDN": null,
                "accountNumber": null,
                "customerName": null,
                "amountPaid": null,
                "payerClientCode": null,
                "paymentDate": null,
                "clientName": null,
                "currencyCode": null,
                "paymentID": null,
                "refundAmount": null
            }
        ]
    }
}

Failure Response

{
    "status": {
        "statusCode": 1001,
        "statusDescription": "No payment available for refund"
    },
    "results": null
}

Authentication Failure Response

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