...
Refund is basically payment resource related to specific order where sender and destination accounts are switched comparing to original payment created to collect money from the merchant’s customer (when merchant’s customer paid to merchant).
They can, similarly to payments, be processed by one of two flows:
Redirect flow
Embedded flow
A single order can have multiple refunds.
...
Refund initialization requests and responses are very similar to order initialization https://everifin.atlassian.net/wiki/spaces/EPAD/pages/2562228372/Payment+Orders#Order-initialization.
Request body
Field | Type | Optional | Description |
|---|---|---|---|
instructionId | text, unique (max 64 chars) | yes | Your unique identification string. Can be used to match the refund with data in client’s data stores. Also used to prevent duplicated refunds - see below. |
amount | number (0.01 - 9999999999) | no | Amount to be refunded |
currency | text, valid currency (min/max 3 chars) | no | Currency of the payment. Must be a valid currency code, e.g. EUR, CZK, PLN. |
recipientIban | text, valid iban (max 50 chars) | yes | IBAN account number of customer. Money will be refunded to this account. Can be also specified after the refund is initiated. |
senderBankId | text, valid bank identifier in Everifin | no | ID of your’s bank, from which the money will be sent |
senderIban | text, valid iban (max 50 chars) | yes | IBAN of sender's bank account |
variableSymbol | numeric text (max 10 chars) | yes | Symbol for SK/CZ market. Cannot be combined with reference. |
constantSymbol | numeric text (max 10 chars) | yes | Symbol for SK/CZ market. Cannot be combined with reference. |
specificSymbol | numeric text (max 4 chars) | yes | Symbol for SK/CZ market. Cannot be combined with reference. |
reference | text (max 35 chars) | yes | Payment reference. Cannot be combined with symbols. |
redirectUrl | text (max 5000 chars) | no | Redirect URL back to your system. This redirect URL has to be whitelisted in Everifin Paygate. It must be string satisfying URL rules. E.g. hostname must contain at least one dot (for local development URL like this can be used: http://yourapp.local/xyz). Custom query parameters are accepted. |
paymentMessage | text (max 140 chars) | yes | Message to your customer. This message will be visible in his bank transaction as description of the transfer. |
recipientName | text (max 140 chars) | yes | Name of your customer. This name will appear in your’s bank transaction as recipient of the money. |
userLocale | language code | yes | If you want to force Everifin Paygate UI language for your customer, use this property. List of supported languages: 'en', 'sk', 'cs' (it is being extended continuously) . If not defined, browser language will be applied. |
reason | text (max 255 chars) | yes | Text describing the reason why the customer was refunded |
Example call
| Code Block |
|---|
POST {everifin_url}/api/v2/orders/{order_id}/refunds
{
"instructionId": "ABCD11234",
"amount" : 0.55,
"currency": "EUR",
"recipientIban": "SK132465798132456",
"recipientName": "John Doe",
"variableSymbol": "0000000001",
"constantSymbol": "0308",
"specificSymbol": "0000000003",
"reference": null,
"redirectUrl": "https://thebesteshopintheworld.com",
"paymentMessage": "Refund from the best eshop",
"reason": "Goods not available"
} |
Response
Field | Type | Optional | Description |
|---|---|---|---|
id | uuid, unique | no | Refund ID |
orderId | uuid, unique | no | Order ID |
link | text | no | Redirect URL to Everifin Paygate |
status | enum | no | Refund status |
Example response
| Code Block |
|---|
200:
{
"meta": {
"status": "SUCCESS"
},
"data": {
"id": "72470a28-4501-49bf-a9fd-8fc67813a51b",
"orderId": "970fb439-7d63-4633-957f-7104c29324d6",
"status": "CREATED",
"link": "http://pay.everifin.local/l/3b68bdf2-6203-49d3-8563-b9f0d79bd6d3"
}
} |
...
Create refund endpoint can return error codes described in the following table:
code | description |
|---|---|
REFUND_LIMIT_EXCEEDED | Refund limit for an order was exceeded. Refund limit is compared against sum of all order’s refunds, which are not FAILED, WITHDRAWN or EXIPRED plus the amount of requested refund. If the requested sum of refunds is higher than the limit specified and calculated in the order (see refundLimitPercentage), this error is thrown. To change the refund limit for an order, call Update Order endpoint and set the refundLimitPercentage to a higher value (or 0, if the limit should not be checked) |
REFUND_CANNOT_BE_CREATED | Refund can not be created for an order at this moment. Possible reason is that no payment was initialized for the order, yet. Refunds can be only initialized for orders, whose payment’s processing was started. |
REFUND_DUPLICATED | The same refund was already created. To prevent duplicated refunds, it is not possible to create two identical refunds for a single order. To create a refund with the same payment data (amount, reference etc.), change at least instructionId (which should be unique) or reason. |
NOT_AUTHORIZED | Client is not authorized to create refund. Refunds scope might be missing. |
Refund processing
Refunds can be processed via:
...
by redirecting to the URL from the Refund initialization response
...
embedded flow - by calling the Process Refund endpoint with the ID of a refund retrieved from the Refund initialization response
. Processing of refunds is basically the same as processing of order’s payments with difference in redirect URL parameter.For instructions how to use the embedded flow for refund processing, see
| Info |
|---|
Once the refund payment is processed by payer, redirect back to merchant contains query parameter |
...
endpoint Process Refund must be called
refund data can be enriched with recipientIban, if it’s not specified during refund initialization
...
Error codes
In addition to error codes specified for the Process Order Payment endpoint, note also the following error codes:
code | description |
|---|---|
MISSING_RECIPIENT_IBAN | Refund has no recipientIban specified. First specify the recipientIban through the Refund Process endpoint. |
Refund withdrawal
You can withdraw (invalidate / cancel) a refund by calling Everifin Paygate endpoint with DELETE method. The refund cannot be withdrawn for finalized refunds (successful or failure) and also in case the user has already started a refund authorization on bank’s side.
On details, how to use this endpoint, see the Postman documentation: https://documenter.getpostman.com/view/21056419/2s9Y5Ww3LU#af3ff169-8a87-42e0-91ae-689bb44d75bb
Error codes
code | description |
|---|---|
REFUND_CANNOT_BE_WITHDRAWN | Refund’s state does not allow to withdraw it. Payment might be processing at the moment or was already processed |
Refund detail
Refund detail endpoint can be used to check the status of a refund.
...