Initiate Refund

This API enables you process refund to a customer for a transaction.

Webhook Events and Request Structure are sent to merchants who have configured a webhook to receive notifications upon completion of a transaction refund.

Note: Webhook notifications are sent when a refund has either succeeded or failed.

This endpoint is protected with OAuth 2.0 Bearer token. To find out more about authorization for Monnify endpoints, check Here

Endpoint URL: {{base_url}}/api/v1/refunds/initiate-refund

HTTP Method: POST

The {{base_url}} for test is https://sandbox.monnify.com but when you go live, it changes to the live url

Initiate Refund Request

{
    "transactionReference": "tranRef",
	"refundReference":"merchantRefundRef",
	"refundAmount": 1000.56,
	"refundReason": "Order cancelled! (limited to 64 characters)",
	"customerNote": "A note to be sent to customer (limited to 16 characters)",
	"destinationAccountNumber": "Optional account number to send the refund amount to",
	"destinationAccountBankCode": "Optional bank code to identify the destination bank"
}

Initiate Refund Response

{
   "requestSuccessful":true,
   "responseMessage":"success",
   "responseCode":"0",
   "responseBody":{
	  "refundReference": "refundReference",
      "transactionReference":"MNFY|0111231|123412342",
	  "refundReason": "Order was cancelled",
      "customerNote": "Refund-orderJ111",
      "refundAmount":1200,
      "refundStatus":"IN_PROGRESS",
      "refundType":"FULL_REFUND",
      "createdOn":"17/03/2021 3:32:09 AM",
      "completedOn":"",
      "comment":"Transaction refund is in progress."
   }
}

Field Reference

Field	Description	Constraints
transactionReference	Unique identifier for the transaction generated by Monnify.	Mandatory
refundAmount	Amount to refund. Minimum value is N100, and maximum is total transaction amount. If not specified, total transaction amount will be refunded.	Optional - Defaults to transactionAmount.
refundReason	A note describing reason why this transaction is being refunded.	Mandatory - limited to a 64 character sentence.
customerNote	An optional note which will be serve as narration in credit to customer's bank account.	Optional - If provided, it should be limited to a 16 character sentence.
refundStatus	Status of the refund. Possible values are IN_PROGRESS, FAILED, COMPLETED.
refundType	FULL_REFUND or PARTIAL_REFUND. FULL_REFUND is refund amount is total transaction amount.
createdOn	The data/time refund was initiated.
completedOn	Date and time refund was completed to customer.
comment	Comment describing status of the refund. If FAILED, comment will contain the reason for the failure.
refundReference	Unique identifier for the transaction refund generated by the merchant. This value would be used to retrieve the details of a transaction refund.	Mandatory - Unique reference generated by the merchant to identify the refund.
destinationAccountNumber	Optional account number to send the refund amount to. Defaults to the customer account number on the transaction record.	Optional - If provided, you must also provide the destinationAccountBankCode.
destinationAccountBankCode	Optional bank code for the destinationAccountNumber. This value would be used to identify the destination bank. Defaults to the customer bank code on the transaction record.	Optional - If provided, you must also provide the destinationAccountNumber.

Response Codes

When a refund is initiated, the following response codes may be returned.

Response Code	Response Message
0	Request is received successfully and will be processed.
R1	Transaction with specified reference does not exist.
R2	Refund not permitted for specified transaction.
R3	Specified refund amount is above transaction amount.
R4	Specified refund amount is below minimum refund amount.
R5	Merchant does not have sufficient funds to process refund.
R6	Customer account details are invalid. N.B.: Every payment made by customers contains the sender's account details, and that is where refunds are sent to. However, on rare occasions, the sender's account details aren't sent to Monnify. To handle this scenario, include the customer's valid destinationAccountNumber and destinationAccountBankCode in your request body
R7	No refund was initiated with the supplied refund reference.
R8	supplied value has exceeded the maximum allowed number of characters.
R9	Supplied refund reference already exists for the merchant.
R10	Merchant account balance could not be retrieved.
R11	Name inquiry network error.
R12	The total amount of all refunds done on a particular transaction has exceeded the transaction amount.
M01	System error. Contact support.
M02	System error. Contact support.