Callback mechanism

From Barion Documentation
Jump to navigation Jump to search

Payment callback mechanism (aka. IPN)

Whenever a given payment's state changes, it is expected that the caller system and the Barion database are synchronized. This is accomplished by implementing the callback mechanism (referred to as "Instant Payment Notification" or "IPN" in some terminology) between the two systems.

The callback process

The event flow of the implemented callback mechanism is simple:

  1. The payment gets completed, cancelled, expired, refunded, taken under investigation, or released from investigation
  2. The Barion system sends an HTTP POST request to the merchant's system to the URL defined by the merchant (in the CallbackUrl parameter of the /v2/Payment/Start API call) with the payment's unique identifier, indicating that something has just happened, so the merchant's system should check the payment now
  3. The merchant's system sends a request to the /v2/Payment/GetPaymentState API endpoint with its POSKey and the received payment identifier
  4. Based on the response received, the merchant's system can determine what processing tasks should take place

Structure and processing of the callback request

The callback request contains one parameter, the payment identifier. This is sent in the paymentId field of the POST request body. The merchant's system must send an HTTP 200 OK response (with any content) in order for the callback to be considered successful. The timeout period for answering a callback request is 15 seconds.

If the Barion system does not get an HTTP 200 response, it retries sending the callback for a maximum of 5 times, with exponential back-off timing delay between tries:

  • 2 seconds
  • 6 seconds
  • 18 seconds
  • 54 seconds
  • 2 minutes 42 seconds

So the total time window allocated for successful callback is roughly 4 minutes. If the Barion system fails to get an HTTP 200 response after that, the callback is not sent and the merchant's system automatically gets an e-mail notification about the error.

Every time, when your system receives a callback request from the Barion you have to call the /v2/Payment/GetPaymentState API endpoint to find out the change. First, your system should check the payment's status and after the list of the payment's transactions. For example, if you requested a payment refund or when the reserved payment's time limit has expired the list of payment’s transactions will contain new e-money transactions. It's your system's responsibility to handle changes.


Never rely on the callback function alone. When the callback URL is requested, your application must call the /v2/Payment/GetPaymentState Barion API to get the proper payment state.

Please refer to the Security Measures page for more information and a list of IP addresses.

The IP address of the callback request may change any time for security reasons.

Why you should use it

When a Barion Smart Gateway payment process takes place between the two systems, neither of them can rely purely on explicit user interaction to process things. In such situations, the Barion system must inform the merchant's system that the payment has changed in some way, without involving the user.

Here are some examples:

  • the payment is completed, but the user closed their browser or lose network connection, preventing them from returning to the webshop or application that redirected them to the Barion Smart Gateway
  • the user explicitly cancels the payment, but closes their browser instead of navigating back to the merchant
  • the payment is never completed and expires because of the time window limit
  • the payment is refunded

Implementing callback handling will save you time and pain tracking such "lost" payments. It also eases the troubleshooting with your customers, since you will always have valid data on your side.

Rate limiting

Currently only live in the test environment, production go-live date will be announced soon

If you implement the callback mechanism, you may misuse the getpaymentstate requests in many ways. Some of the possible worst practices:

  • After payment start, you do not wait for the callback from Barion, but send continuous getpaymentstate requests for the same paymentID. This request burst can cause unnecessary overhead in our systems.
  • If a problem occurs during the payment and it does not finish successfully, you keep requesting getpaymentstate for that ID indefinitely with some time interval. This frequency itself is not a problem, but as time passes there are more and more phantom requests which in sum can cause a great load.

Because of these possible misuses, we implemented rate limiting on calling getpaymentstate:

  • In case of the first scenario we accept only two getpaymentstate requests with the same paymentID in every 5 seconds. So the first two requests will be served, then every additional request during the 5 seconds interval will be denied with http status code 429 "Too many requests".
  • For the second scenario we count the getpaymentstate requests with the same paymentID. When this count reaches a certain limit during a well-defined time period, requests with the same ID will be banned with the above http status code. The exact timeframe and limit count is not public.

What NOT to do

Never long-poll the /v2/Payment/GetPaymentState API endpoint and wait for the payment status to suddenly change! If you use a high interval between requests, user experience will deteriorate significantly. If you use a small interval, your requests will get throttled.

If you are having difficulties implementing the proper callback flow, consult our developer support!