Transaction Refunds

See Transaction Refund API for more information on implementing it on your platform.

Types of Refunds

• Partial Refund: A part of the total transaction amount is to be refunded. The customer will be refunded a part of the initial full payment.

• Full Refund: The total transaction amount is to be refunded.

Charges

For payments made via transfers, you will be charged a refund fee of N10 and this will be deducted from your wallet. You are required to have your wallet funded before refunds can be processed.

Virtual account payments:

Monnify does not refund to virtual account numbers. If the original payment was made via a virtual account, refunding to that same account will fail. In such cases, the merchant must collect a regular bank account number from the customer and specify it as the refund destination. See Refunding to a Different Account below.

Refund via API

Activation Required:

Refund are not enabled by default. You must request activation for the API (and UI - if needed) to be enabled both your Sandbox and/or Live environments. Contact [email protected] to get this enabled stating your use case for the feature. As part of the email, you will be expected to idemnify Monnify for potential use and misuse of the feature on your platfrom.

All refund API calls require a valid bearer token. Authenticate first using your API key and secret, then use the returned token in the Authorization header.

Partial Refund

A partial refund returns only a portion of the original transaction amount. Set refundAmount to any value less than the full transaction amount.

Full Refund

A full refund returns the entire transaction amount. Set refundAmount to the original transaction amount. You can optionally specify a different destination account; if omitted, the refund is sent back to the originating account.

Refunding to a Different Account

By default, Monnify sends the refund to the account that made the original payment. You can override this by supplying destinationAccountNumber and destinationAccountBankCode in the request body.

Virtual account payments require a different destination:

Monnify does not refund to virtual account numbers. Virtual accounts are temporary receive-only accounts — transfers back to them will fail. If a customer paid through a virtual account (i.e. a dynamic account number generated for the transaction), ask them to provide a regular bank account number and use it as the destinationAccountNumber when initiating the refund.

Request Fields

Response

Get Refund Status

Poll this endpoint to check the current status of a refund using the refundReference you supplied when initiating it.

Prefer webhooks over polling:

Polling is useful for a one-time status check, but for production systems configure a webhook URL to receive real-time refund notifications instead. See the section below.

Refund Webhooks

Monnify sends a webhook notification to your configured URL when a refund reaches a terminal state. There are two refund event types:

Successful Refund

Sent when the refund has been processed and the customer's account has been credited.

Failed Refund

Sent when the refund could not be processed. Use the refundReference to look up further details or surface an error to your support team.

Setting Up Your Webhook URL

Configure your webhook URL in the Monnify dashboard under Settings > API Keys & Webhooks. All webhook notifications include a monnify-signature header containing an HMAC-SHA512 hash of the request body signed with your client secret. Always verify this signature before processing the payload.

Webhook best practices:

• Respond with HTTP 200 immediately on receipt. Do your processing after acknowledging.
• Verify the monnify-signature header before trusting the payload.
• Check for duplicate notifications using refundReference before crediting or updating order state.
• Whitelist Monnify's IP addresses on your server firewall.

See Webhooks & Event Types for the full signature verification guide and code samples in Node.js, PHP, and Java.

Refund From Monnify Dashboard

To initiate a refund on a particular transaction, click on the transaction to view its details as shown below;

Clicking on the "Refund" button takes you to the refund page;

Finally populate the necessary fields and click on the refund button to perform a refund on such transaction.

Sample Error Messages