DocumentationRecipesAPI ReferencesSupportBlog
Documentation

Refunds

Learn how to process refunds.

Suggest Edits

You can refund a transaction easily with our APIs. To initiate a refund, send a request to the refund endpoint with the transaction ID in the URL. You can also specify the amount to be refunded in the body if you wish to make a partial refund.

The refund amount will be deducted from your available balance. Additionally, you can attach 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 above code will initiate the refund process, and you will get a similar response to the one below:

{
  "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"
  }
}

Refunded transactions can have different statuses depending on the payment type. Here are other refund statuses.

Refund statusExplanation
completedGeneral status for completed refunds.
completed-bank-transferStatus for completed bank transfer refunds.
completed-momoRefund status for completed mobile money transactions.
completed-mpgsRefund status for completed card transactions.
completed-offlineStatus for refunds completed manually outside of the Flutterwave application, e.g., Point-of-Sale or cash transactions.
completed-preauthA subset of completed-mpgs. This is the refund status of preauth card transactions.
pending-momoStatus for pending mobile money refunds.
processingStatus for refunds that are currently being treated. This is a transient state between initiated and completed refunds.

To verify the final status of your refunds, you can choose any of the following methods:

  • Specify a Callback URL: Include the callbackurl field in your request body, and we will send the refund details to that URL when the refund is either completed or fails.
  • Manually check the status: Use the “Fetch a refunded transaction” endpoint with the refund ID (provided in the response above) to retrieve the current status of the refund.
  • Enable webhooks: If webhooks are enabled, we will send a notification to your webhook URL with the refund details once the refund is either completed or fails.

📘

Webhooks

By default webhooks will not be sent for refunds, you will need to reach out to the internal team to enable your account to receive webhooks for refunds.

Updated 10 days ago