Refunds
- Michal Gregor
- Martin Plank
Each processed order can be refunded using refunds API described here: Refunds API
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).
A single order can have multiple refunds.
The maximum amount of the refund is restricted by the value specified in the field “refundLimitPercentage“ provided in the request body when creating the order. By default (if not specified) it is 100% (meaning the same amount as the amount of the order). If set to 0, the limit is not applied.
Refund initialization
To initialize a refund, you send the information about refunded amount and payment sender/recipient information. Everifin responds with an refund ID and redirect link pointing to Everifin Paygate page.
Refund initialization requests and responses are very similar to order initialization 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
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
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"
}
}Checking of duplicated refunds
InstructionId of a refund should be unique. If instructionId is supplied by the client, Everifin paygate checks, whether an identical refund already exists. If an identical refund already exists, the request is denied to prevent accidentally created refunds.
Refund is considered to be duplicated, if all of these values are equal for existing refund:
instructionId
amount
reason
reference
variableSymbol
specificSymbol
constantSymbol
recipientIban
paymentMessage
Also, a matching refund must not be in states FAILED, WITHDRAWN or EXPIRED.
Error codes
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 by redirecting to the URL from the Refund initialization response. Processing of refunds is basically the same as processing of order’s payments with difference in redirect URL parameter.
Once the refund payment is processed by payer, redirect back to merchant contains query parameter refundId holding ID of the refund payment. Using this parameter’s value the detail of the refund payment can be obtained (Refunds | Refund detail).
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: Everifin PayGate v2
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.
Documentation: Everifin PayGate v2
List of order’s refunds
To get all order’s refunds, use the Order Refunds endpoint.
Documentation: Everifin PayGate v2
List of all refunds
To search refunds without the context of an order, use the Search Refunds endpoint.
See the Postman documentation for instructions how to use this endpoint - filtering, sorting and pagination is supported.
Documentation: Everifin PayGate v2