Callback mechanism

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:

1. Set up a webhook listener endpoint (that implements the processing logic detailed on this page).
2. Provide your listener’s URL when setting up a payment (as a required parameter to the payment start endpoint call).
3. The Barion server sends real-time state change notifications to the listener about the payment.
4. 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.

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

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

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

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

5. After determining that the customer attempted to pay, the listener logic should check both PaymentStatus and the Transactions array in the endpoint response.

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