Refunds

You can refund disputed transactions easily using our APIs. To initiate a refund, send a request to the refund endpoint with the original transaction ID(data.id). For partial refunds, specify the refund amount. The refund amount is deducted from your available balance. You can also add a note to the refund by specifying comments.

// Install with: npm i flutterwave-node-v3

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY);
const response = await flw.Transaction.refund({
    id: transactionId,
    amount: amountToRefund,
    comments: "Product out of stock.",
});

# Install with: gem install flutterwave_sdk

require 'flutterwave_sdk'

flw = Flutterwave.new(ENV["FLW_PUBLIC_KEY"], ENV["FLW_SECRET_KEY"], ENV["FLW_ENCRYPTION_KEY"])
transactions = Transactions.new(flw)
response = transactions.initiate_a_refund {
    id: transaction_id,
    amount: amount_to_refund,
    comments: "Product out of stock.",
}
print response

curl --request POST 'https://api.flutterwave.com/v3/transactions/75923/refund' \
  --header 'Authorization: Bearer YOUR_SECRET_KEY'\
  --header 'Content-Type: application/json'\
  --data-raw '{
    "amount": 6900,
    "comments": "Product out of stock."
}'

The request initiates the refund process. A successful response looks similar to the following:

{
  "status": "success",
  "message": "Transaction refund initiated",
  "data": {
    "id": 75923,
    "account_id": 73362,
    "tx_id": 908790,
    "flw_ref": "URF_1577867664541_3572735",
    "wallet_id": 74639,
    "amount_refunded": 6900,
    "status": "completed",
    "destination": "payment_source",
    "meta": {
      "source": "availablebalance"
    },
    "created_at": "2021-01-24T09:18:37.366Z"
  }
}

🚧
The minimum refund amount is NGN 100 and KES 10. Refund request below the applicable minimum returns a 400 Bad Request validation error.

{
    "status": "error",
    "message": "Amount should be above NGN100",
    "data": null
}

Refund statuses

Refunds go through different stages before completion. Depending on the payment method used to charge the customer originally, these can have several statuses. Here is a list of supported refund statuses:

Refund status	Explanation
`completed`	Refund has been initiated and is pending disbursement to the customer.
`completed-bank-transfer`	Refund to Bank Account was successful.
`completed-momo`	Refund to Mobile Money (MOMO) was successful.
`completed-mpgs`	Refund was successful.
`completed-offline`	Refund was processed successfully offline or manually.
`completed-preauth`	A subset of `completed-mpgs`. This indicates a successful refund for preauth card transactions.
`pending-momo`	Refund to Mobile Money (MOMO) is pending.
`pending-bank-transfer`	Refund to Bank Account is pending.
`pending-mpgs`	Card refund is pending.
`processing`	Refund is being processed.

Card refunds are completed within 3-15 days after initiation. Refunds to mobile money wallets take 3-5 days, while refunds to bank accounts are completed within 24 hours.

Verify a refund

📘
If you specify a callbackurl in your refund request, it overrides the refund webhook URL configured in your dashboard for that request.

You can check the final status of a refund using any of the following methods.

Specify a callback URL: Include the callbackurl field in your request body to receive refund notifications at the specified URL when the refund is completed or fails
Manually check the status: Call the Fetch a refunded transaction endpoint with the refund ID (data.id returned in the initiate refund response) to retrieve the current status of the refund.
Enable webhooks for refunds: You can configure a custom URL to receive webhook notifications when a refund is completed or fails.

To configure your refund webhook URL:

Log in to your Flutterwave Dashboard.
Go to Settings → Webhooks.
Click Switch to V3 webhook if V3 Webhooks is not already selected.
Under Webhook preferences, click View for Webhook preferences with custom url.
Enable webhook for refunds and enter your custom URL.
Save your changes.

{
  "id": 89074,
  "AmountRefunded": 5000,
  "status": "completed",
  "FlwRef": "flwm3s4m0c1754324273641",
  "destination": "payment_source",
  "comments": "&quot;refunds for ABC goods",
  "settlement_id": "NEW",
  "meta": "{\"source\":\"ledgerbalance\",\"callbackurl\":\"https://webhook.site/0457f7f7-b760-4c54-9dfd-aa6696515751\",\"isPartialRefund\":true,\"disburse_ref\":\"CC-REFD-92026611744-flwm3s4m0c1754324273641\",\"disburse_status\":\"failed\"}",
  "createdAt": "2025-08-04T16:18:31.000Z",
  "updatedAt": "2025-08-04T16:18:32.000Z",
  "deletedAt": null,
  "walletId": 134244,
  "AccountId": 92319,
  "TransactionId": 8784082
}

🚧

Refund statuses

Verify a refund

📘If you specify a callbackurl in your refund request, it overrides the refund webhook URL configured in your dashboard for that request.

📘
If you specify a `callbackurl` in your refund request, it overrides the refund webhook URL configured in your dashboard for that request.