The order resource in Everifin Paygate API tries to reflect merchant’s order (in most cases there is relationship: one order - one payment, but some merchants have concept of orders with posibility of multiple payments - customers can add items to the same order later when some items of the order were already paid).
The payment process starts with creating the payment order. There is one related payment resource created automatically with each new order (amount is equal as the amount of the whole order).
Order can be updated (e.g. amount adjusted Update Order endpoint) and the result is based on the status of the related payment resource:
when payment has not been initialized yet - order and related payment is updated
when payment has been processed already - new payment is created and added to order
Once the order is created, it can be further processed by one of two flows:
Redirect flow (using Everifin GUI)
Embedded flow (full API flow without using Everifin GUI)
All available endpoints related to orders are described here: Orders API
Order initialization
In order initialization you send the information about the order and its first payment to Everifin. Everifin responds with an order ID, processable payment ID and redirect link pointing to Everifin Paygate page.
Request
HTTP headers
Initiation of a order must contain following headers.
Header | Type | Description |
|---|---|---|
Authorization | Bearer token | Authorization token to access API. |
Body
Field | Type | Optional | Description |
|---|---|---|---|
instructionId | text, unique (max 64 chars) | yes | Your unique identification string. |
amount | number (0.01 - 9999999999) | no | Amount of the payment. |
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) | no | Your IBAN account number to collect the payment (not payer`s IBAN). This IBAN must be whitelisted in Everifin Paygate, otherwise the payment will be denied. |
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. |
customerEmail | valid email | yes | Email of the customer |
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 | Your name in case you don’t want to use the registered name. This name will appear in payer’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. |
refundLimitPercentage | Valid positive number (Integer or floating up to 2 decimals) or zero | yes | Specifies the refund limit of an order. If value equals 100, refund can be created up to the amount of an order. If set to 0, the refund limit is not applied, i.e. any amount can be refunded. |
externalId | Free text, maximum 255 characters | yes | Can be used to match the order with data in client's systems. Might be different from instructionId, because the instructionId could be unique for each payment within an order. |
Example call
POST {everifin_url}/api/v2/orders
{
"instructionId": "ABCD11234",
"amount" : 1.05,
"currency": "EUR",
"recipientIban": "SK132465798132456",
"recipientName": "The best e-shop in the world",
"variableSymbol": "0000000001",
"constantSymbol": "0308",
"specificSymbol": "0000000003",
"reference": null,
"redirectUrl": "https://thebesteshopintheworld.com",
"paymentMessage": "Payment for The best eshop",
}
Response
Field | Type | Optional | Description |
|---|---|---|---|
id | uuid, unique | no | Order ID |
processablePaymentId | uuid, unique | no | Payment ID (not your instruction id from the request) |
link | text | no | Redirect URL to Everifin Paygate |
status | enum | no | Order status |
Example response
200:
{
"meta": {
"status": "SUCCESS"
},
"data": {
"id": "bf4f2fa8-9426-441d-b450-67a5c801a9ef",
"processablePaymentId": "372f9684-184b-437b-b974-e3331bbc879a",
"link": "{{redirect-to-everifin}}",
"status": "UNPAID"
}
}