post https://api-approval.tingg.africa/v3/checkout-api/refund/request
This function allows a merchant to refund payments that were already acknowledged as received and processed successfully
This function allows a merchant to refund payments that were already acknowledged as received and processed successfully
Live Endpoint
| Key | Value Type | Required | Description |
|---|---|---|---|
currency_code | String | No | 3 letter currency code for the transaction |
merchant_transaction_id | String | Yes | Unique transaction ID identifying the transaction as given by the merchant. (Has a limit of 100 characters) |
refund_type | String | Yes | A flag indicating the type of refund to be done; can either be Full or Partial. |
amount | Double | Yes | Amount to be refunded. Compulsory for partial |
refund_narration | String | Yes | A reason for the refund. (Has a limit of 100 characters) |
refund_reference | String | Yes | Reference number for the transaction. (Has a limit of 100 characters) |
service_code | String | Yes | The merchant's service code. |
Response Status Codes
| Status Code | Description |
|---|---|
| 200 | Success. Refund request successfully logged in the checkout platform. |
| 500 | Failure. Generic failure occurred. Could be as a result of a system failure on the checkout platform. |
| 1001 | No request found. |
| 1007 | Missing country code. The checkout request posted was missing a country_code |
| 1013 | Not JSON. The checkout request posted was not valid JSON |
| 1014 | Missing merchant transaction id. The request did not have a merchant_transaction_id |
| 1015 | Missing checkout request id.The request did not have a checkout_request_id |
| 1017 | Invalid charge msisdn provided. The charge_msisdn provided was not valid in the country provided |
| 1027 | Invalid amount provided. The charge_amount should be between the minimum and maximum amounts provided for the payment option. |
| 422 | Invalid request |
Refund status codes
These request status codes indicate the status of a refund when a query status or a refund notification is processed.
| Request status code | Description | Available from |
|---|---|---|
| 184 | This is indicates that a refund of part of the request amount has been initiated. | Query request status |
| 185 | This is indicates that full refund the request amount has been initiated. | Query request status |
| 186 | This is indicates that the part refund for the request was successfully processed. | Query request status and Refund Notification |
| 187 | This is indicates that the full refund for the request was successfully processed. | Query request status and Refund Notification |
| 191 | Refund Expired | Query request status and Refund Notification |
Refund Notification
Notifications are done for final refund status codes 186, 187, and 191.
Refund notification is configurable. To receive a final status notification on refund, configure a Refund Notification Url for the service under Service Settings on the gateway portal as shown below.
Refund Notification request
Key Value Type Description amount double the refunded amount statusCode int the status of the refund refundReference String Reference number for the transaction (sent when initiating a refund) merchantTransactionId String Unique transaction ID identifying the transaction as given by the merchant.
Sample Refund Notification Request{ "amount":30.5, "statusCode":186, "refundReference":"536772882hhd", "merchantTransactionID":"tywvbb63778383" }
