Guides
API ReferenceCreate Account
Start typing to search…

Refunds API

The Refunds API allows merchants to refund successful transactions via API. The API enables merchants to automate refunds and retrieve refund details when needed.

📘

Currency Support

Refunds via API is only available for NGN payments. We will be extending support to other currencies soon.


Refund Status

The different statuses for a refund include:

  • Processing: This indicates that the refund is being processed.
  • Failed: This indicates that the refund failed due to an error or rejection (e.g., invalid source account).
  • Success: This indicates that the refund is successfully completed and the customer has been refunded.

Initiate a Refund

To initiate a refund for a pay-in transaction using the API, make a request to the following endpoint:

https://api.korapay.com/merchant/api/v1/refunds/initiate


The request body should have the following parameters:

FieldTypeRequired?Description
amountNumberNoThe amount to refund (the complete amount will be refunded if this is not specified).
payment_referenceStringYesThis is the reference of the payment on which you are making a refund.
referenceStringYesThis is the reference derived by the merchant. (Maximum of 50 characters)
reasonStringNoThis is the reason for the refund. (Maximum of 50 characters)

Here are examples of responses for this request:

{
    "status": true,
    "message": "Refund successfully initiated",
    "data": {
        "refund_reference": "TXN-123456",
        "refund_date": "2025-04-03T08:27:22.646Z",
        "status": "processing",
        "payment_reference": "TXN-234",
        "reason": "Customer requested refund",
        "amount_returned": 120,
        "currency": "NGN"
    }
}
{
    "status": false,
    "message": "Amount can't be more than NGN 2000",
    "data": null
}

Retrieving Details of a Refund

To retrieve the details of a refund, send a request to the following endpoint:

https://api.korapay.com/merchant/api/v1/refunds/:reference


This request should include the following parameters:

ParameterTypeRequired?Description
referenceStringYesThis is the ID/reference of the refund to be fetched.

The response to this request could look like this:

{
   "status": true,
   "message": "Refund details retrieved successfully",
   "data": {
      "amount": "2000.00",
      "status": "processing",
      "currency": "NGN",
      "destination": "customer",
      "reference": "TXN-123456",
      "reason": "Customer requested refund",
      "payment_reference": "TXN-234",
      "transaction_amount": "2000.00",
      "payment_method": "card",
      "created_at": "2025-04-03 09:27:22",
      "completed_at": null
   }
}
{
   "status": false,
   "message": "Refund not found",
   "data": null
}

Retrieving the Details of a List of Refunds

You can also retrieve a list of refunds within a specified time period. To do this, make a request to the following endpoint:

https://api.korapay.com/merchant/api/v1/refunds


The request should have the following parameters:

ParameterTypeRequired?Description
currencyStringNoThis specifies the currency for filtering the refunds.
date_fromStringNoStart date for fetching the refunds (YYYY-MM-DD)
date_toStringNoEnd date for fetching the refunds (YYYY-MM-DD)
limitNumberNoThis defines the maximum number of refund records to return on a single request.
starting_afterStringNoThis returns results starting after the provided refund cursor.
ending_beforeStringNoThis returns results ending before the provided refund cursor.
statusStringNoThis specifies the status for filtering refunds. The status can either be processing, failed or success.

Here's an example of the response to this request:

{
   "status": true,
  	"message": "Refunds retrieved successfully",
   "data": {
       "has_more": true,
       "refunds": [
           {
               "pointer": "cus_706",
               "reference": "TXN-123456",
               "status": "success",
               "amount": "120.00",
               "currency": "NGN",
               "payment_reference": "TXN-234",
               "reason": "Customer requested refund",
               "transaction_amount": "2000.00",
               "created_at": "2025-04-03 09:27:22",
               "completed_at": 2025-04-03 09:30:22
           }
          ]
         }
}
{
    "status": false,
    "message": "Internal server error. It would be nice if you report this to us.",
    "data": null
}

Webhook Notification for Refunds

We send webhook notifications on successful and failed refunds initiated via the API. See a sample webhook response below

{  
  "event": "refund.success",
  "data": {
    "amount": 100,
    "status": "success",
    "currency": "NGN",
    "reference": "123456",
    "payment_reference": "KPY-PAY-0lIrV1pRG",
    "refund_date": "2025-01-10 10:00:04",
    "completion_date": "2025-01-10 11:30:00"
  }
}

Updated 3 days ago