This API enables you process refund to a customer for a transaction.
...
| Info | ||
|---|---|---|
| ||
POST: https://sandbox.monnify.com/api/v1/refunds/initiate-refund |
Please note that this endpoint is protected using OAuth2 Token. Visit Authentication section of this document for details on OAuth2 Token.
...
| 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"
} |
Response
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"requestSuccessful": true,
"responseMessage": "success",
"responseCode": "0",
"responseBody": {
"transactionReferencerefundReference": "MNFY|0111231|123412342ref001",
"paymentReferencetransactionReference":"J_12312_122", "transactionAmount": 5000"MNFY|0111231|123412342",
"refundAmount": 1200,
"refundStatus": "IN_PROGRESS",
"refundReason": "Order was cancelled",
"customerNote": "Refund for order J1110",
"refundType": "FULL_REFUND",
"createdOn": "15/12/2020 09:38:13 AM",
"completedOn": "15/12/2020 12:20:23 PM2021-04-20 17:21:37.179",
"comment": "Refund processed successfullyTransaction refund is in progress."
}
} |
Field Reference
| Field | Description | Constraints |
transactionReference | Unique identifier for the transaction generated by Monnify. | YesMandatory |
refundAmount | Amount to refund. Minimum value is N10, and maximum is total transaction amount. If not specified, total transaction amount will be refunded. | No. Optional - Defaults to transactionAmount. |
| refundReason | A note describing reason why this transaction is being refunded. | YesMandatory - limited to a 64 character sentence. |
| customerNote | An optional note which will be serve as narration in credit to customer's bank account. | NoOptional - 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. |
| R7 | No refund has been 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. |