This API enables you process refund to a customer for a transaction.
Endpoint
...
| title | Endpoint |
|---|
...
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.
| Info |
|---|
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
...
Please note that this endpoint is protected using OAuth2 Token. Visit Authentication section of this document for details on OAuth2 Token.
-refund
HTTP Method: POST
| Info |
|---|
The {{base_url}} for test is |
Initiate Refund Request
| Code Block | |||||||
|---|---|---|---|---|---|---|---|
| |||||||
{
"transactionReference": "tranRef",
"refundReference":"merchantRefundRef",
"refundAmount": 1000.56,
"refundReason": "Order cancelled! (limited to 64 characters)",
"customerNote": "AnA optional 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
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"refundReference": "refundReference",
"transactionReference": "MNFY|0111231|123412342",
"paymentReferencerefundReason":"J_12312_122 "Order was cancelled",
"transactionAmount "customerNote": 5000,
"Refund-orderJ111",
"refundAmount": 1200,
"refundStatus": "IN_PROGRESS",
"refundReason": "Order was cancelled", "customerNote": "Refund for order J1110",
"refundType": "FULL_REFUND",
"createdOn": "1517/1203/20202021 093:3832:1309 AM",
"completedOn": "15/12/2020 12:20:23 PM",
"",
"comment": "Refund processed successfully."
"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. |