<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
	<id>https://docs.barion.com/api.php?action=feedcontributions&amp;feedformat=atom&amp;user=Geleim</id>
	<title>Barion Documentation - User contributions [en]</title>
	<link rel="self" type="application/atom+xml" href="https://docs.barion.com/api.php?action=feedcontributions&amp;feedformat=atom&amp;user=Geleim"/>
	<link rel="alternate" type="text/html" href="https://docs.barion.com/Special:Contributions/Geleim"/>
	<updated>2026-11-21T05:50:09Z</updated>
	<subtitle>User contributions</subtitle>
	<generator>MediaWiki 1.43.11</generator>
	<entry>
		<id>https://docs.barion.com/index.php?title=Callback_mechanism&amp;diff=2984</id>
		<title>Callback mechanism</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Callback_mechanism&amp;diff=2984"/>
		<updated>2021-02-04T14:11:25Z</updated>

		<summary type="html">&lt;p&gt;Geleim: /* What NOT to do */ This has been pretty muched cleared up above&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{PageTitle|title=Payment callback mechanism (aka. IPN)}}&lt;br /&gt;
{{TableOfContents}}&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Whenever a given payment&#039;s state changes, it is expected that the caller system and the Barion database are synchronized. This is accomplished by implementing the &#039;&#039;&#039;callback mechanism&#039;&#039;&#039; (referred to as &#039;&#039;&amp;quot;Instant Payment Notification&amp;quot;&#039;&#039; or &#039;&#039;&amp;quot;IPN&amp;quot;&#039;&#039; in some terminology) between the two systems.&lt;br /&gt;
&lt;br /&gt;
== The callback process ==&lt;br /&gt;
&lt;br /&gt;
The event flow of the implemented callback mechanism is simple:&lt;br /&gt;
&lt;br /&gt;
# The payment gets completed, cancelled, expired, refunded, taken under investigation, or released from investigation&lt;br /&gt;
# The Barion system sends an &#039;&#039;&#039;HTTP POST&#039;&#039;&#039; request to the merchant&#039;s system to the URL defined by the merchant (in the &amp;lt;code&amp;gt;CallbackUrl&amp;lt;/code&amp;gt; parameter of the [[Payment-Start-v2|/v2/Payment/Start]] API call) with the payment&#039;s unique identifier, indicating that something has just happened, so the merchant&#039;s system should check the payment now&lt;br /&gt;
# The merchant&#039;s system sends a request to the [[Payment-GetPaymentState-v2|/v2/Payment/GetPaymentState]] API endpoint with its POSKey and the received payment identifier&lt;br /&gt;
# Based on the response received, the merchant&#039;s system can determine what processing tasks should take place&lt;br /&gt;
&lt;br /&gt;
== Structure and processing of the callback request ==&lt;br /&gt;
&lt;br /&gt;
The callback request contains one parameter, the payment identifier. This is sent in the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; field of the POST request body. The merchant&#039;s system must send an &amp;lt;code&amp;gt;HTTP 200 OK&amp;lt;/code&amp;gt; response (with any content) in order for the callback to be considered successful. The timeout period for answering a callback request is &#039;&#039;&#039;15 seconds&#039;&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
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:&lt;br /&gt;
* 2 seconds&lt;br /&gt;
* 6 seconds&lt;br /&gt;
* 18 seconds&lt;br /&gt;
* 54 seconds&lt;br /&gt;
* 2 minutes 42 seconds&lt;br /&gt;
So the total time window allocated for successful callback is roughly &#039;&#039;&#039;4 minutes&#039;&#039;&#039;. If the Barion system fails to get an HTTP 200 response after that, the callback is not sent and the merchant&#039;s system automatically gets an e-mail notification about the error.&lt;br /&gt;
&lt;br /&gt;
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&#039;s status and after the list of the payment&#039;s transactions. For example, if you requested a payment refund or when the reserved payment&#039;s time limit has expired the list of payment’s transactions will contain new e-money transactions. It&#039;s your system&#039;s responsibility to handle changes.&lt;br /&gt;
&lt;br /&gt;
== Security ==&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
Please refer to the [[Security Measures]] page for more information and a list of IP addresses.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=The IP address of the callback request may change any time for security reasons.|color=#FF7A3D}}&lt;br /&gt;
&lt;br /&gt;
== Why you should use it ==&lt;br /&gt;
&lt;br /&gt;
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&#039;s system that the payment has changed in some way, without involving the user.&lt;br /&gt;
&lt;br /&gt;
Here are some examples:&lt;br /&gt;
&lt;br /&gt;
* 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&lt;br /&gt;
* the user explicitly cancels the payment, but closes their browser instead of navigating back to the merchant&lt;br /&gt;
* the payment is never completed and expires because of the time window limit&lt;br /&gt;
* the payment is refunded &lt;br /&gt;
&lt;br /&gt;
Implementing callback handling will save you time and pain tracking such &amp;quot;lost&amp;quot; payments. It also eases the troubleshooting with your customers, since you will always have valid data on your side.&lt;br /&gt;
&lt;br /&gt;
== Rate limiting ==&lt;br /&gt;
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. &#039;&#039;&#039;Generally, you should rely on the callback mechanism whenever possible unless you have a specific reason not to&#039;&#039;&#039;, but if you want to manually get the details of a payment, here&#039;s a couple of things to bear in mind:&lt;br /&gt;
* 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&lt;br /&gt;
* 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&#039;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&lt;br /&gt;
&lt;br /&gt;
To avoid these situations, the following throttling logic is implemented on our API:&lt;br /&gt;
* 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 &amp;quot;Too many requests&amp;quot; error.&lt;br /&gt;
* 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.&lt;br /&gt;
&lt;br /&gt;
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&#039;s a reason to do so.&lt;/div&gt;</summary>
		<author><name>Geleim</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Callback_mechanism&amp;diff=2983</id>
		<title>Callback mechanism</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Callback_mechanism&amp;diff=2983"/>
		<updated>2021-02-04T14:10:49Z</updated>

		<summary type="html">&lt;p&gt;Geleim: /* Rate limiting */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{PageTitle|title=Payment callback mechanism (aka. IPN)}}&lt;br /&gt;
{{TableOfContents}}&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
Whenever a given payment&#039;s state changes, it is expected that the caller system and the Barion database are synchronized. This is accomplished by implementing the &#039;&#039;&#039;callback mechanism&#039;&#039;&#039; (referred to as &#039;&#039;&amp;quot;Instant Payment Notification&amp;quot;&#039;&#039; or &#039;&#039;&amp;quot;IPN&amp;quot;&#039;&#039; in some terminology) between the two systems.&lt;br /&gt;
&lt;br /&gt;
== The callback process ==&lt;br /&gt;
&lt;br /&gt;
The event flow of the implemented callback mechanism is simple:&lt;br /&gt;
&lt;br /&gt;
# The payment gets completed, cancelled, expired, refunded, taken under investigation, or released from investigation&lt;br /&gt;
# The Barion system sends an &#039;&#039;&#039;HTTP POST&#039;&#039;&#039; request to the merchant&#039;s system to the URL defined by the merchant (in the &amp;lt;code&amp;gt;CallbackUrl&amp;lt;/code&amp;gt; parameter of the [[Payment-Start-v2|/v2/Payment/Start]] API call) with the payment&#039;s unique identifier, indicating that something has just happened, so the merchant&#039;s system should check the payment now&lt;br /&gt;
# The merchant&#039;s system sends a request to the [[Payment-GetPaymentState-v2|/v2/Payment/GetPaymentState]] API endpoint with its POSKey and the received payment identifier&lt;br /&gt;
# Based on the response received, the merchant&#039;s system can determine what processing tasks should take place&lt;br /&gt;
&lt;br /&gt;
== Structure and processing of the callback request ==&lt;br /&gt;
&lt;br /&gt;
The callback request contains one parameter, the payment identifier. This is sent in the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; field of the POST request body. The merchant&#039;s system must send an &amp;lt;code&amp;gt;HTTP 200 OK&amp;lt;/code&amp;gt; response (with any content) in order for the callback to be considered successful. The timeout period for answering a callback request is &#039;&#039;&#039;15 seconds&#039;&#039;&#039;.&lt;br /&gt;
&lt;br /&gt;
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:&lt;br /&gt;
* 2 seconds&lt;br /&gt;
* 6 seconds&lt;br /&gt;
* 18 seconds&lt;br /&gt;
* 54 seconds&lt;br /&gt;
* 2 minutes 42 seconds&lt;br /&gt;
So the total time window allocated for successful callback is roughly &#039;&#039;&#039;4 minutes&#039;&#039;&#039;. If the Barion system fails to get an HTTP 200 response after that, the callback is not sent and the merchant&#039;s system automatically gets an e-mail notification about the error.&lt;br /&gt;
&lt;br /&gt;
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&#039;s status and after the list of the payment&#039;s transactions. For example, if you requested a payment refund or when the reserved payment&#039;s time limit has expired the list of payment’s transactions will contain new e-money transactions. It&#039;s your system&#039;s responsibility to handle changes.&lt;br /&gt;
&lt;br /&gt;
== Security ==&lt;br /&gt;
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.&lt;br /&gt;
&lt;br /&gt;
Please refer to the [[Security Measures]] page for more information and a list of IP addresses.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=The IP address of the callback request may change any time for security reasons.|color=#FF7A3D}}&lt;br /&gt;
&lt;br /&gt;
== Why you should use it ==&lt;br /&gt;
&lt;br /&gt;
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&#039;s system that the payment has changed in some way, without involving the user.&lt;br /&gt;
&lt;br /&gt;
Here are some examples:&lt;br /&gt;
&lt;br /&gt;
* 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&lt;br /&gt;
* the user explicitly cancels the payment, but closes their browser instead of navigating back to the merchant&lt;br /&gt;
* the payment is never completed and expires because of the time window limit&lt;br /&gt;
* the payment is refunded &lt;br /&gt;
&lt;br /&gt;
Implementing callback handling will save you time and pain tracking such &amp;quot;lost&amp;quot; payments. It also eases the troubleshooting with your customers, since you will always have valid data on your side.&lt;br /&gt;
&lt;br /&gt;
== Rate limiting ==&lt;br /&gt;
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. &#039;&#039;&#039;Generally, you should rely on the callback mechanism whenever possible unless you have a specific reason not to&#039;&#039;&#039;, but if you want to manually get the details of a payment, here&#039;s a couple of things to bear in mind:&lt;br /&gt;
* 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&lt;br /&gt;
* 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&#039;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&lt;br /&gt;
&lt;br /&gt;
To avoid these situations, the following throttling logic is implemented on our API:&lt;br /&gt;
* 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 &amp;quot;Too many requests&amp;quot; error.&lt;br /&gt;
* 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.&lt;br /&gt;
&lt;br /&gt;
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&#039;s a reason to do so.&lt;br /&gt;
&lt;br /&gt;
== What NOT to do ==&lt;br /&gt;
&lt;br /&gt;
Never long-poll the [[Payment-GetPaymentState-v2|/v2/Payment/GetPaymentState]] API endpoint and wait for the payment status to suddenly change! &lt;br /&gt;
If you use a high interval between requests, user experience will deteriorate significantly. If you use a small interval, your requests will get throttled.&lt;br /&gt;
&lt;br /&gt;
If you are having difficulties implementing the proper callback flow, consult our developer support!&lt;/div&gt;</summary>
		<author><name>Geleim</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=FundingInformation&amp;diff=2902</id>
		<title>FundingInformation</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=FundingInformation&amp;diff=2902"/>
		<updated>2021-01-11T14:22:01Z</updated>

		<summary type="html">&lt;p&gt;Geleim: Added &amp;#039;softdecline&amp;#039; process result&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{PageTitle|title=Funding information structure}}&lt;br /&gt;
&lt;br /&gt;
This structure represents the details about a funding source that was used when completing a payment. At the moment this is only used when the funding source is a bank card.&lt;br /&gt;
&lt;br /&gt;
= API usage =&lt;br /&gt;
&lt;br /&gt;
This structure is used by the following API endpoints:&lt;br /&gt;
* [[Payment-GetPaymentState-v2]]&lt;br /&gt;
&lt;br /&gt;
= Property list =&lt;br /&gt;
&lt;br /&gt;
{{api_output_table_header}}&lt;br /&gt;
|-&lt;br /&gt;
| BankCard || [[BankCard]] || The bank card used to complete the payment.&lt;br /&gt;
|-&lt;br /&gt;
| AuthorizationCode || string || The authorization code received by the card processing system when executing the payment.&lt;br /&gt;
|-&lt;br /&gt;
| ProcessResult || string || The result of the card payment. Possible values:&lt;br /&gt;
* Successful: the card transaction was successful&lt;br /&gt;
* ProblemWithCard: the card transaction was unsuccessful, there may be a problem with the card&lt;br /&gt;
* LowFunds: the card transaction was unsuccessful due to insufficient funds&lt;br /&gt;
* LostOrStolenCard: the credit card has been reported lost or stolen&lt;br /&gt;
* CardNotSupported: the payment card is not supported at the time of the transaction&lt;br /&gt;
* Declined:  the payment card was declined by the acquirer&lt;br /&gt;
* FraudulentTransaction: potentially fraudulent transaction, the monitoring system declined the transaction&lt;br /&gt;
* CardSystemError: the card transaction failed due to the card system&lt;br /&gt;
* SystemError: system error, in this case we try to refund the transaction amount if we have enough information to initiate it&lt;br /&gt;
* SoftDeclined: the payment card did not support SCA at the time of the transaction&lt;br /&gt;
|-&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Geleim</name></author>
	</entry>
</feed>