Paygate Payment Flow
- Juraj Malecka
- Michal Gregor
- Martin Plank
- Michal Ondrovic
The payment flow can be described by the picture below.
Steps
The payment flow has these steps:
Common step Authentication - first your system needs to be authenticated to Everifin Paygate. See Authentication
API v1
Payment initialization - payment is initiated via API and user is redirected to Everifin Paygate to process the payment. See Redirect Flow (v1)
Get payment(s) - you can get payment data for single payment or payment list. This can be used to check payment status in case you do not use hooks. See Payment Endpoints | Get payments
API v2
Order initialization - redirect URL and payment ID are present in the response
Order processing - Redirecting to URL obtained in step 1. Details can be found here: Redirect Flow
Checking status
By getting the detail of the specific payment in the order (Get Order Payment endpoint) - this approach should be used in case you use scenario “One payment for one order” in your online business
in case your business case allows multiple successful payments for one order (e.g. allowing to add items to order after it was successfully paid) - getting the order detail (Get Order endpoint) - it provides detail of the order together of details of all its payments
Payment statuses
During the payment process the payment changes its status. The status defines not only state of the payment, but also possible operations - payments in some statuses cannot be updated or cancelled.
Status | Final | Withdrawable | Description |
|---|---|---|---|
CREATED | no | yes | Payment is created and waiting for the user. |
SEEN | no | yes | User opens the Everifin Paygate web page or processing via Process Order endpoint is started. |
PROCESSING | no | no | The payment is being processed (user is authorizing payment on bank`s page or authorization is done and payment is being processed in the bank). |
CONFIRMED | no | no | The payment has been successfully authorized in the bank by the payer. In some edge cases we might not receive any further status from the bank. In such cases we do not know for sure if the payment is successful or not, even though, from our experience, in vast majority of the cases the payment is eventually successful. For details see Paygate Payment Flow | Recommended reactions to payment statuses and Paygate Payment Flow | Edge cases |
BOOKED | yes | no | The payment has been booked (settled) in the bank. |
WITHDRAWN | yes | no | The payment has been withdrawn by merchant. |
FAILED | yes | no | Payment has failed. Field |
EXPIRED | yes | no | Payments that stay in CREATED or SEEN for a long time are eventually moved to this state. |
PROCESSING_EXPIRED | yes | no | The payment is being processed, but we are unable to retrieve its status from the bank, because access granted by the payer has expired. |
Recommended reactions to payment statuses
The following table describes recommendations on the behavior of the merchant’s system once it obtains the payment status. This normally happens in these cases:
merchant’s “thank you” web page displayed after the customer is redirected back from Everifin Paygate (or when customer goes back in browser)
webhook (if implemented by merchant).
Status | Situation | Thank you page behavior | Webhook behavior |
|---|---|---|---|
CONFIRMED | The payment authorization was successful | In most of the cases this means successful payment. In some edge cases it might not be the case and eventually the payment will fail (rejected by the bank). For some businesses it might be OK to take the risk and consider this status as successful if the timing of product/service delivery is crucial and if it is acceptable to deal with the missing payment afterwards. The risk can be fully mitigated by connecting the destination bank account to Everifin Paygate system. The payments will be paired by our system also against transactions appearing in the bank account. Please contact us if you want to discuss this in more detail. | Depends on the merchant’s decision. |
BOOKED | The payment has been already settled at the payer’s bank. | Information about the successful payment is displayed to customer. | The merchant’s order should be updated to reflect the payment success and further processes related to this fact can be initiated (invoice generation, notification email to customer, shipping process etc.). |
FAILED EXPIRED | The payment was not successful. | Information about the unsuccessful payment should be displayed to customer. Customer should be able to restart only the checkout process with existing shopping cart (so there is no need to start the whole shopping process over). | The merchant’s order should be updated to reflect the unsuccessful payment. Further actions related to this fact could be initiated (e.g. notification email sent to customer containing the link to page of the existing order where the customer could redo the checkout (with different payment method for example). |
WITHDRAWN | The merchant withdrew the payment via API call (possible only when the customer has not yet started the authorization process). | The explanation why the payment has been withdrawn by the merchant should be displayed. | The merchant’s system already has the confirmation the withdrawal of the payment has been successful (in the response of the withdraw API call), so probably nothing has to be done anymore by webhook. |
PROCESSING_EXPIRED | We are not able to get the payment status from the bank anymore (the grant given by the customer in the bank for us to get the payment status expired). This is rare edge case. Usually when customer leaves the payment authorization process. | Here the merchant has multiple options. The decision might be based on the business specifics (i.e. what goods or services is the merchant selling, if it is crucial to know the payment status instantly or the merchant can endure some delay - e.g. waiting with shipping until receiving of the money is confirmed on the bank account). We are offering also service of connecting the collection bank account to cover these cases. Some behavior options:
| Similar to “thank you” page behavior. |
PROCESSING | In some edge cases it might happen the bank is processing the payment bit longer and the customer is informed by this fact by Paygate and then redirected back to merchant. This status describes the fact we are still checking the payment status. | In this case it is also up to the merchant what behavior he chooses (depends on his business and preferences). Some possible options:
| The merchant’s system may update related order to status reflecting the payment is already being processed. |
CREATED SEEN | The payment is only initiated by the merchant system via API (CREATED) or has been seen on paygate web page by customer (SEEN). The payment can be in this statuses if the customer does not start the authorization and goes back in the browser and gets to “thank you” page. | If the customer gets to “thank you” page, merchant could withdraw the payment by calling withdraw endpoint and then let the customer restart the checkout process. If the customer chooses Everifin again, new payment would be initiated by the merchant’s system. After the withdraw of the payment the behavior could continue as in the case of statuses FAILED or EXPIRED. If the payment is not withdrawn, it will expire in 30 minutes (status EXPIRED). | No action when the payment is moved to SEEN as it indicates the customer visited the Everifin payment page and might continue with authorization. |
Payment status flow chart
Following diagram illustrates possible transitions between payment states:
Payment Failure reason codes
Reason code | Description |
|---|---|
CANCELED_BY_PAYER_AT_EVERIFIN | Payer rejected the payment on Everifin Paygate page before authorization has been initiated. |
BANK_NOT_FOUND | Payer has not found the desired bank and wants to choose different payment method at the merchant's site. |
MANUAL_TRANSFER_REQUESTED | Payer has not found the desired bank and decided to receive payment details for the manual bank transfer via email (generating and sending the email to customer need to be handled by merchant). This feature is turned off by default. |
CANCELED_BY_PAYER_AT_BANK | Payer canceled the payment on the bank’s page. |
INSUFFICIENT_AMOUNT | Payer does not have enough funds on his account to make the payment. |
AML_BLOCKED | Payer’s funds have been blocked at the bank as a result of bank’s AML checks. Payer needs to contact the bank to treat the situation further. |
REJECTED_BY_BANK | The bank rejected the payment due to some failure. Issue needs to be further analyzed (sometimes the reason is the payer canceled the payment on the bank’s pages but we are not able to identify this situation because the bank does not inform about it). |
OTHER | Other, unspecified failure reasons (e.g. payment authorization failed, bank API temporary outage etc.) |
Order statuses
Status | Withdrawable | Description |
|---|---|---|
UNPAID | yes | Payment of the order is not paid yet. The order is withdrawable in this status in case the related payment is in one of statuses CREATED and SEEN. |
PARTIALLY_PAID | no | Payment of the order is paid but order amount is higher than the paid payment amount (this can happen by updating the order with higher amount what creates another payment in the order which is to be paid). |
PAID | no | The order is fully paid. |
API v1 vs. v2
Main differences between API v1 and v2 are:
API v2 introduced concept of orders and refunds, which are not supported in API v1
API v1 is considered deprecated and can be removed in the future.
Edge cases
This section describes rare edge cases that can appear during payment processing.
AML checks
As part of the payment processing the banks do the AML checks. If the transaction does not pass the AML checks successfully (e.g. the payment is identified by the bank’s rules as suspicious, the payer is on some AML lists etc.), the bank blocks the funds and the payment ends up in FAILED state (reason code: AML_BLOCKED). The payer needs to contact his bank in such situation.
Non-compliant banks
Even though the situation is still improving, some banks, however, do not comply with the PSD2 regulation in all details.
We are working very proactively with the regulators and the bank’s support teams in order to achieve better quality PSD2 APIs.
Confirmed payment failure
In case of some banks, in rare cases, the payment which has been successfully authorized by the payer (CONFIRMED status) may be eventually rejected by the bank. Together we can find out if it applies to your business case (banks, country etc.).
This risk can be fully mitigated by connecting destination bank account to Everifin Paygate system. The payments are then paired (checked) against transactions appearing in the bank account. Please contact us if you want to discus this in more detail.