This API enables you process refund to a customer for a transaction.
...
Note: Webhook notifications are sent when a refund has either succeeded or failed.Endpoint
| Info |
|---|
This endpoint is protected with OAuth 2.0 Bearer token |
Endpoint
...
URL:{{base_url}}/api/v1/refunds/initiate-refund
...
Please note that this endpoint is protected by OAuth 2.0 Bearer Token
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": "An 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",
"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 N10, 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 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. |