Refunds

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).

They can, similarly to payments, be processed by one of two flows:

Redirect flow
Embedded flow

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 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
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). Using of URL like this for local development requires some locally running proxy rerouting to your app running on localhost. 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 via:

redirect flow - by clicking the link 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.

For instructions how to use the embedded flow for refund processing, see https://everifin.atlassian.net/wiki/spaces/EPAD/pages/2467561560/Embedded+Flow#3.-Process-Order-Payment. There are two differences with the payment processing in the embedded flow:

endpoint Process Refund must be called
refund data can be enriched with recipientIban, if it’s not specified during refund initialization

In the Postman documentation, you can find various examples on how to use the Process Refund endpoint.

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.

Documentation: https://documenter.getpostman.com/view/21056419/2s9Y5Ww3LU#b88e9eab-e428-4192-9116-650f5bde9a18

List of order’s refunds

To get all order’s refunds, use the Order Refunds endpoint.

Documentation: https://documenter.getpostman.com/view/21056419/2s9Y5Ww3LU#c0e5d94f-e328-48f2-9d91-0d2db6e75959

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: https://documenter.getpostman.com/view/21056419/2s9Y5Ww3LU#83d3e8cf-23dd-457e-befe-3049cddcba3f