Latest revision as of 13:09, 18 October 2024

Payment callback mechanism (aka. IPN)

Learn how to subscribe to the Barion callback mechanism, a webhook service that helps you track the state changes of payments in real time.

The basic idea is that to help automate your payment processing, the Barion server sends notifications about updates to the payments in your Barion shop, which should make your Barion shop query the Barion API’s payment state endpoint for the specifics of the status change.

Here’s an overview of the steps involved:

Set up a webhook listener endpoint (that implements the processing logic detailed on this page).
Provide your listener’s URL when setting up a payment (as a required parameter to the payment start endpoint call).
The Barion server sends real-time state change notifications to the listener about the payment.
The notification triggers your listener endpoint logic.

This page offers an overview of the Barion callback mechanism (an implementation of the Instant Payment Notification (IPN) concept), best practices, and troubleshooting tips.

The callback process

Whenever there’s a change in the status of a payment transaction, the Barion server sends a HTTP POST request to the CallbackUrl parameter you passed to the Payment/Start call when you created the payment.

This improves scalability, and avoids potential delays in your payment processing caused by polling intervals.

The Barion server sends a POST request to the CallbackUrl you specified, with the PaymentId identifying the updated payment.

This is merely an indication that there’s an update to query.
Your listener should acknowledge receipt of the POST request with a HTTP 200 OK response within 15 seconds.

The Barion server only accepts HTTPS-protocol requests that are using TLS v1.2 and above.

The Barion server re-sends the webhook up to 5 more times after the initial 15-second window, with increasing delays between calls (2 seconds, 6 seconds, 18 seconds, 54 seconds, and 102 seconds).

If the server doesn’t get a HTTP 200 OK after the fifth call (and 4 minutes’ total waiting time), it sends an error message email to your Barion shop’s registered email address.
After acknowledging the request, your listener should make a call to the Payment/<PaymentId>/PaymentState API endpoint to query the payment transaction’s new status.
Your listener logic should check the PaymentStatus to see if the payment is still active:
- Canceled indicates that the customer has closed the checkout page without starting a payment process, or before the payment process could finish.
- Expired indicates that the customer let the payment window elapse without completing the payment – they most likely abandoned the checkout page.
  
  An Expired reservation payment automatically gets refunded, which generates a new refund-type transaction in the endpoint response’s Transactions array.
It’s recommended to reach out to your customer in these cases, and attempt to change their minds about the payment.
After determining that the customer attempted to pay, the listener logic should check both PaymentStatus and the Transactions array in the endpoint response.
Based on the payment state endpoint response, and considering the payment scenario, your listener should process the payment according to your business logic.

Fallback mechanism

If a callback is not received, the PaymentState API endpoint should be called as a fallback to retrieve the status of the payment. This ensures that the payment status is still updated, even if the callback doesn’t come through. The PaymentState API should be called in the following cases if the callback is not received:

After redirection: the PaymentState endpoint should be called after the customer is redirected to the RedirectUrl.
After payment window expiry: if a final status is not received via callback notification or if the customer has not been redirected, the PaymentState API should be called approximately 15 minutes after the payment window expires. This accounts for scenarios where the payment process may still be completed by the customer, even if the window has officially closed.

Payment scenarios

Immediate payment

A “Succeeded” payment status indicates that all transactions in the payment went through.

Reservation payment

Reservation payment setup

A “Reserved” payment status indicates that the reservation is successfully set up.

Reservation payment finishing
- “Succeeded” payment status: all transactions in the payment have been finished with the initially reserved amount
- “PartiallySucceeded” payment status: some, but not all transactions have been finished with the initially reserved amount
- A new refund-type transaction in the endpoint response’s Transactions array: a transaction in a reserved payment was finished with a lower amount than the initially reserved amount, and the difference is automatically refunded to the user in a new transaction

Delayed capture

Delayed capture payment setup

An “Authorized” payment status indicates that the customer completed the payment, and the payment funds are blocked on their payment instrument.

Delayed capture payment capturing
- “Succeeded” payment status indicates that the payment was successfully captured.

Even if the captured amount is lower that the previously-authorized amount, no refund transaction is generated, because the difference is simply released directly on the payer’s payment instrument.

Refund

A new refund-type transaction is added to the Transactions array in the endpoint response.

Note that only previously “Succeeded” payment transactions can be refunded, and that the status of these payments won’t change regardless of whether the refund was successful or not.

Best practices

Rate limiting

Throttling is in place to prevent service disruption caused by excessive requests to the payment state endpoint: if you call the endpoint with the same `PaymentID` more than once within a 5-second interval, for the following 5 seconds, further calls to the endpoint the request return the `HTTP 429 Too many requests` error.

If the number of requests with the same `PaymentID` exceeds a certain threshold within a certain time window, all further requests will return `HTTP 429 Too many requests`.

IP allowlisting

To protect your webhook listener endpoint from unauthorized requests, it’s strongly recommended to allowlist the Barion API IP addresses, and blocklist all other IPs.

Production environment Barion API IP address

40.113.73.229

Sandbox Barion API IP address

20.223.214.216

@@ Line 3: / Line 3: @@
-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.
+Learn how to subscribe to the Barion callback mechanism, a webhook service that helps you track the state changes of payments in real time.
-== The callback process ==
+The basic idea is that to help automate your payment processing, the Barion server sends notifications about updates to the payments in your Barion shop, which should make your Barion shop query the Barion API’s payment state endpoint for the specifics of the status change.
-The event flow of the implemented callback mechanism is simple:
+Here’s an overview of the steps involved:
-# The payment gets completed, cancelled, expired, refunded, taken under investigation, or released from investigation
+# Set up a webhook listener endpoint (that implements the processing logic detailed on this page).
-# The Barion system sends an '''HTTP POST''' request to the merchant's system to the URL defined by the merchant (in the <code>CallbackUrl</code> parameter of the [[Payment-Start-v2|/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
+# Provide your listener’s URL when setting up a payment ([[Payment-Start-v2|as a required parameter to the payment start endpoint call]]).
-# The merchant's system sends a request to the [[Payment-GetPaymentState-v2|/v2/Payment/GetPaymentState]] API endpoint with its POSKey and the received payment identifier
+# The Barion server sends real-time state change notifications to the listener about the payment.
-# Based on the response received, the merchant's system can determine what processing tasks should take place
+# The notification triggers your listener endpoint logic.
-{{NotificationBox|title=IMPORTANT|text=Always process the entire response with all included transaction data, because different actions make different changes to the payment state object.|color=#FF7A3D}}
+This page offers an overview of the Barion callback mechanism (an implementation of the [https://en.wikipedia.org/wiki/Instant_payment_notification Instant Payment Notification (IPN)] concept), best practices, and troubleshooting tips.
-== Structure and processing of the callback request ==
+<span id="the-callback-process"></span>
+== The callback process ==
-The callback request contains one parameter, the payment identifier. This is sent in the <code>paymentId</code> field of the POST request body. The merchant's system must send an <code>HTTP 200 OK</code> 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 [[Payment-GetPaymentState-v2|/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.
-== Actions initiating a callback, and how to detect them ==
-Different actions result in different changes in the payment state object that you query on the [[Payment-GetPaymentState-v2|/v2/Payment/GetPaymentState]] API endpoint. Depending on what happened in the payment's life cycle, there are different things to look for. This section should help you choose what checks to perform based on your integration scenario. Please read these thoroughly and perform all applying checks in your business logic when processing a callback.
-'''Successful payment'''
-When the customer successfully completes the payment, the payment status will be set to different values depending on the type of the payment.
-* <code>Successful</code> when using Immediate payments
-* <code>Reserved</code> when using Reservation payments
-* <code>Authorized</code> when using Delayed Capture payments
-'''Payment rejection'''
+Whenever there’s a change in the status of a payment transaction, the Barion server sends a HTTP POST request to the <code>CallbackUrl</code> parameter you passed to [[Payment-Start-v2|the Payment/Start call]] when you created the payment.
-When the customer decides to reject payment, and return to the shop, the payment status will be set to <code>Canceled</code>. The payment can no longer be completed.
+This improves scalability, and avoids potential delays in your payment processing caused by polling intervals.
-'''Finishing a Reservation payment'''
+<ol style="list-style-type: decimal;">
+<li><p>The Barion server sends a POST request to the <code>CallbackUrl</code> you specified, with the <code>PaymentId</code> identifying the updated payment.</p>
+<p>This is merely an indication that there’s an update to query.</p></li>
+<li><p>Your listener should acknowledge receipt of the POST request with a <code>HTTP 200 OK</code> response within 15 seconds.</p>
+<blockquote>The Barion server only accepts HTTPS-protocol requests that are using TLS v1.2 and above.</blockquote>
+<p>The Barion server re-sends the webhook up to 5 more times after the initial 15-second window, with increasing delays between calls (2 seconds, 6 seconds, 18 seconds, 54 seconds, and 102 seconds).</p>
+<p>If the server doesn’t get a <code>HTTP 200 OK</code> after the fifth call (and 4 minutes’ total waiting time), it sends an error message email to your Barion shop’s registered email address.</p></li>
+<li><p>After acknowledging the request, your listener should make a call to [[Payment-PaymentState-v4|the Payment/<PaymentId>/PaymentState]] API endpoint to query the payment transaction’s new status.</p></li>
+<li><p>Your listener logic should check the [[05-api-reference/01-payment-resource/04-payment-resource-enums/04-payment-status|<code>PaymentStatus</code>]] to see if the payment is still active:</p>
+<ul>
+<li><p><code>Canceled</code> indicates that the customer has closed the checkout page without starting a payment process, or before the payment process could finish.</p></li>
+<li><p><code>Expired</code> indicates that the customer let the payment window elapse without completing the payment – they most likely abandoned the checkout page.</p>
+<p>An <code>Expired</code> reservation payment automatically gets refunded, which generates a new refund-type transaction in the endpoint response’s [[05-api-reference/01-payment-resource/01-payment-state#transactions|<code>Transactions</code>]] array.</p></li></ul>
-When the shop finishes a Reservation payment, the payment status will be set depending on the finish being partial or full.
+<blockquote><p>It’s recommended to reach out to your customer in these cases, and attempt to change their minds about the payment.</p></blockquote></li>
-* if there are multiple payment transactions, but only certain one of them are being finished, the payment status will NOT change (it will stay in <code>Reserved</code>)
+<li><p>After determining that the customer attempted to pay, the listener logic should check both [[05-api-reference/01-payment-resource/04-payment-resource-enums/04-payment-status|<code>PaymentStatus</code>]] and the [[05-api-reference/01-payment-resource/01-payment-state#transactions|<code>Transactions</code>]] array in the endpoint response.</p></li>
-* when every transaction in the payment has been finished, the payment status will be set to <code>Succeeded</code>
+<li><p>Based on the payment state endpoint response, and considering [[#payment-scenarios|the payment scenario]], your listener should process the payment according to your business logic.</p></li></ol>
-* transactions finished with a lower amount than the initial reserve will result in a partial refund to the user, which shows up as a new refund transaction in the Transactions[] array of the payment state object
-'''Capturing a Delayed Capture payment'''
+=== '''Fallback mechanism''' ===
+If a callback is not received, the [[Payment-PaymentState-v4|PaymentState]] API endpoint should be called as a fallback to retrieve the status of the payment. This ensures that the payment status is still updated, even if the callback doesn’t come through. The [[Payment-PaymentState-v4|PaymentState]] API should be called in the following cases if the callback is not received:
-When the shop captures a Delayed Capture payment, the payment status will be set to <code>Succeeded</code>, regardless to whether the authorization and capture amounts match. No refund transaction is being created in this case, because the partial capture happens directly on the bank card.
+* After redirection: the [[Payment-PaymentState-v4|PaymentState]] endpoint should be called after the customer is redirected to the <code>RedirectUrl</code>.
+* After payment window expiry: if a final status is not received via callback notification or if the customer has not been redirected, the [[Payment-PaymentState-v4|PaymentState]] API should be called approximately 15 minutes after the payment window expires. This accounts for scenarios where the payment process may still be completed by the customer, even if the window has officially closed.<br />
-'''Payment expiring'''
-When a payment expires without being completed, the payment status will be set to <code>Expired</code>.
+=== Payment scenarios ===
-* If the payment was an ongoing Reservation payment that hasn't been finished in time, a refund will also be created, which shows up as a new refund transaction in the payment state object
+<span id="immediate-payment"></span>
+==== Immediate payment ====
-'''Refund'''
+A “Succeeded” payment status indicates that all transactions in the payment went through.<span id="reservation-payment"></span>
+==== Reservation payment ====
+<span id="reservation-payment-setup"></span>
-When a refund is executed (via the website, or the [[Payment-Refund-v2|/v2/Payment/Refund]] API), a new refund transaction will be added to the Transactions[] array in the payment state object. Only <code>Succeeded</code> payments can be refunded, and the payment status will not change during a refund, it will stay <code>Succeeded</code>. Barion sends a callback for successful and unsuccessful refunds as well. You have to check the refund transaction in the Transactions[] array for the result.
+* Reservation payment setup
-{{NotificationBox|title=IMPORTANT|text=Different actions make different changes to the overall payment state. Never rely only on payment status changes! Always process the entire payment state object and execute your business logic accordingly.|color=#FF7A3D}}
+A “Reserved” payment status indicates that the reservation is successfully set up.<span id="reservation-payment-finishing"></span>
-== Security ==
+* Reservation payment finishing
-Never rely on the callback function alone. When the callback URL is requested, your application must call the [[Payment-GetPaymentState-v2|/v2/Payment/GetPaymentState]] Barion API to get the proper payment state.
+** “Succeeded” payment status: all transactions in the payment have been finished with the initially reserved amount
+** “PartiallySucceeded” payment status: some, but not all transactions have been finished with the initially reserved amount
+** A new refund-type transaction in the endpoint response’s [[05-api-reference/01-payment-resource/01-payment-state#transactions|<code>Transactions</code>]] array: a transaction in a reserved payment was finished with a lower amount than the initially reserved amount, and the difference is automatically refunded to the user in a new transaction
+<span id="delayed-capture"></span>
+==== Delayed capture ====
+<span id="delayed-capture-payment-setup"></span>
-Please refer to the [[Security Measures]] page for more information and a list of IP addresses.
+* Delayed capture payment setup
-{{NotificationBox|title=IMPORTANT|text=The IP address of the callback request may change any time for security reasons.|color=#FF7A3D}}
+An “Authorized” payment status indicates that the customer completed the payment, and the payment funds are blocked on their payment instrument.<span id="delayed-capture-payment-capturing"></span>
-== Why you should use it ==
+* Delayed capture payment capturing
+** “Succeeded” payment status indicates that the payment was successfully captured.
+<blockquote>Even if the captured amount is lower that the previously-authorized amount, no refund transaction is generated, because the difference is simply released directly on the payer’s payment instrument.
+</blockquote><span id="refund"></span>
+==== Refund ====
-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.
+A new refund-type transaction is added to the [[05-api-reference/01-payment-resource/01-payment-state#transactions|<code>Transactions</code>]] array in the endpoint response.
-Here are some examples:
+<blockquote>Note that only previously “Succeeded” payment transactions can be refunded, and that the status of these payments won’t change regardless of whether the refund was successful or not.
+</blockquote><span id="best-practices"></span>
+== Best practices ==
+<span id="rate-limiting"></span>
+=== Rate limiting ===
-* 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
+Throttling is in place to prevent service disruption caused by excessive requests to the payment state endpoint: if you call the endpoint with the same `PaymentID` more than once within a 5-second interval, for the following 5 seconds, further calls to the endpoint the request return the `HTTP 429 Too many requests` error.
-* 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.
+<blockquote>If the number of requests with the same `PaymentID` exceeds a certain threshold within a certain time window, all further requests will return `HTTP 429 Too many requests`.</blockquote><span id="ip-allowlisting"></span>
+=== IP allowlisting ===
-== Rate limiting ==
+To protect your webhook listener endpoint from unauthorized requests, it’s strongly recommended to allowlist the Barion API IP addresses, and blocklist all other IPs.<span id="production-environment-barion-api-ip-address"></span>
-To prevent potential disruptions in our service caused by the abuse of the [[Payment-GetPaymentState-v2|/v2/Payment/GetPaymentState]] API endpoint, we have introduced a rate-limiting feature to throttle excessive requests. '''Generally, you should rely on the callback mechanism whenever possible unless you have a specific reason not to''', but if you want to manually get the details of a payment, here are a couple of things to bear in mind:
+==== Production environment Barion API IP address ====
-* Make sure you do not send continuous requests for the same payment even if you need to get its current state manually without waiting for the callback to happen
-* Do not keep requesting for an indefinite time, even if your requests are throttled (e.g. if a problem occurs during the payment process, and the callback never happens, you shouldn't keep polling the API indefinitely) In this case the frequency is not the problem, but as time passes these orphan requests can cause a great load together
-To avoid these situations, the following throttling logic is implemented on our API:
+.113.73.229<span id="sandbox-barion-api-ip-address"></span>
-* During a 5 seconds window we only accept the first 2 [[Payment-GetPaymentState-v2|/v2/Payment/GetPaymentState]] requests with the same payment ID. This means that if you submit two requests less than 5 seconds apart, subsequent requests will be denied until 5 seconds pass after the initial successful request. These requests will return with an HTTP 429 "Too many requests" error.
+==== Sandbox Barion API IP address ====
-* We keep track of requests, and if requests with the same payment ID reach a certain limit during a specific timeframe, all further requests will return HTTP 429. The exact timeframe and limits are not disclosed to the public.
-To reinforce the points above, we recommend using the callback mechanism described above, and calling the [[Payment-GetPaymentState-v2|/v2/Payment/GetPaymentState]] API endpoint only when there's a reason to do so.
+.223.214.216

Callback mechanism: Difference between revisions