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	Action To Take
0	Request is received successfully and will be processed.
99	Error occurred while processing your request	Engage the Monnify support
R1	Transaction with specified reference does not exist.	Recheck if there’s a transaction with such reference.
R2	Refund not permitted for specified transaction.	Refund is currently only possible for payments via Account_Transfer. Recheck if the transaction is an Account_Transfer payment.
R3	Specified refund amount is above transaction amount.	Recheck the transaction amount and retry accordingly.
R4	Specified refund amount is below minimum refund amount.	The minimum refundable amount is N100.
R5	Merchant does not have sufficient funds to process refund.	Merchant should topup his Monnify wallet and retry.
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	Merchant should request valid account details from the customer or try again later.
R7	No refund was initiated with the supplied refund reference.	Kindly recheck if a refund with the refund reference was successfully initiated .
R8	supplied value has exceeded the maximum allowed number of characters.	The refundReason should not be more than 64 characters and the customerNote should not be more than 16 characters.
R9	Supplied refund reference already exists for the merchant.	Kindly use a new and distinct refund reference.
R10	Merchant account balance could not be retrieved.	Contact Monnify’s support.
R11	Name inquiry network error.	Kindly retry later or Contact Monnify’s support.
R12	The total amount of all refunds done on a particular transaction has exceeded the transaction amount.	No refunds can be done for the particular transaction as the total amount of partial refunds have summed up to the transaction amount.
M01	System error. Contact support.	Contact Monnify’s support.
M02	System error. Contact support.	Contact Monnify’s support.