Refunds allow merchants to return funds to customers for various reasons, such as order cancellations or product unavailability. Using our API, you can seamlessly initiate full or partial refunds, track their status, and monitor refund trends.

Why Refunds Happen?

Refunds may be initiated for several reasons. Common scenarios include:

A customer requests a refund due to dissatisfaction with a product or service.
A customer accidentally overpays (e.g., incorrect pricing or quantity).
A customer pays for an out-of-stock or unavailable item.

Refunding a Customer

To process a refund, send a request to the refunds endpoint using the transaction id.

Your request must include:

amount: The exact amount to be refunded.
reason: A brief note explaining the refund (e.g., Order Cancelled).

curl --request POST \
--url 'https://api.flutterwave.cloud/developersandbox/refunds' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
   "amount":2000,
   "reason":"duplicate",
   "charge_id":"chg_Jwb2Y7ZbJQ"
}'

You'll get a response similar to this:

{
  "message": "Refund Initiated",
  "data": {
    "id": "rfd_eHwAkSdZ48",
    "amount_refunded": 2000,
    "meta": {},
    "reason": "duplicate",
    "status": "completed",
    "charge_id": "chg_Jwb2Y7ZbJQ",
    "created_datetime": "2025-02-13T12:12:22.013525130Z"
  }
}

The refund will be deducted from your available balance or the next settlement.

Refund Status

Refunds can either complete successfully or fail. To track the final status, choose one of the following methods:

Callback URL: Include a callbackurl field in your request. We'll notify this URL once the refund is completed or fails.
Manually Status Check: Query the fetch refunds endpoint using the refundid to retrieve its current status.
Webhooks: If webhooks are enabled, we'll send a notification with the refund status to your webhook URL when processing completes.

Viewing Refund History and Trends

You can analyze your refund activity by retrieving a list of past refunds. Use filters when querying the Fetch Refunds endpoint to narrow results:

page: Page number to retrieve
from: Start date
to: End date
size: Number of results per page

curl --request GET \
--url 'https://api.flutterwave.cloud/developersandbox/refunds?page=1&size=10' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: <YOUR_UNIQUE_TRACE_ID>' \
--header 'X-Idempotency-Key: <YOUR_UNIQUE_INDEMPOTENCY_KEY>' \

You'll get a response similar to this:

{
  "status": "success",
  "message": "Refunds fetched",
  "meta": {
    "page_info": {
      "total": 3,
      "current_page": 1,
      "total_pages": 1
    }
  },
  "data": [
    {
      "id": "rfd_VBwFTccOHT",
      "amount_refunded": 2000,
      "meta": {},
      "reason": "duplicate",
      "status": "completed",
      "charge_id": "chg_ujfv5xWlpX",
      "created_datetime": "2025-02-07T11:08:17.517Z"
    },
    {
      "id": "rfd_9NHHGAilL6",
      "amount_refunded": 150,
      "meta": {},
      "reason": "duplicate",
      "status": "completed",
      "charge_id": "chg_5BBk3iB0oZ",
      "created_datetime": "2025-02-07T09:25:55.555Z"
    },
    {
      "id": "rfd_tSl3PQV6Sc",
      "amount_refunded": 150,
      "meta": {},
      "reason": "duplicate",
      "status": "completed",
      "charge_id": "chg_HvYp0jE07i",
      "created_datetime": "2025-02-06T09:31:52.243Z"
    }
  ]
}