<?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=Vargaj%40barion.dev</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=Vargaj%40barion.dev"/>
	<link rel="alternate" type="text/html" href="https://docs.barion.com/Special:Contributions/Vargaj@barion.dev"/>
	<updated>2026-11-22T10:45:31Z</updated>
	<subtitle>User contributions</subtitle>
	<generator>MediaWiki 1.43.11</generator>
	<entry>
		<id>https://docs.barion.com/index.php?title=Making_a_test_payment&amp;diff=4972</id>
		<title>Making a test payment</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Making_a_test_payment&amp;diff=4972"/>
		<updated>2026-11-07T08:24:58Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: Updated images&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{PageTitle|title=Making a test payment}}&lt;br /&gt;
{| style=&amp;quot;margin-left:2em;&amp;quot; align=&amp;quot;right&amp;quot;&lt;br /&gt;
| __TOC__&lt;br /&gt;
|}&lt;br /&gt;
Get a feel for how Barion works by using the Barion Gateway API to&lt;br /&gt;
&lt;br /&gt;
# set up a payment for the Barion shop you’ve created, and&lt;br /&gt;
# settle the payment with some test money from your Barion Wallet.&lt;br /&gt;
&lt;br /&gt;
== Prerequisites ==&lt;br /&gt;
&lt;br /&gt;
* Completing [[Creating a shop|the first part of this tutorial]].&lt;br /&gt;
* An API testing tool such as [https://www.postman.com/downloads/ Postman]&lt;br /&gt;
&lt;br /&gt;
== Make a test payment using the Barion API ==&lt;br /&gt;
&lt;br /&gt;
1. Log in to [https://secure.test.barion.com to your Barion shop].&lt;br /&gt;
&lt;br /&gt;
2. Click through to Shops&amp;amp;#x3E;Actions&amp;amp;#x3E;Security&amp;amp;#x3E;Secret Key (POSKey), and copy the value to the clipboard.    &lt;br /&gt;
&lt;br /&gt;
[[File:Annotated_security_steps.png]]&lt;br /&gt;
&lt;br /&gt;
[[File:POS_Key.png]]&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=All Barion API endpoints accept standard HTTP1.1 GET or POST method requests, but always one or the other only. Calling an endpoint with the incorrect HTTP method returns a JSON error message.|color=#1798DB}}&lt;br /&gt;
&lt;br /&gt;
3. Start the Postman Desktop agent, and make a POST call to &amp;lt;code&amp;gt;https://api.test.barion.com/v2/payment/start&amp;lt;/code&amp;gt;, passing the following JSON in the request body:  Replace the &amp;lt;code&amp;gt;POSKey&amp;lt;/code&amp;gt; and the &amp;lt;code&amp;gt;Transactions&amp;lt;/code&amp;gt;/&amp;lt;code&amp;gt;Payee&amp;lt;/code&amp;gt; as indicated.&lt;br /&gt;
&amp;lt;syntaxhighlight lang=&amp;quot;json&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;POSKey&amp;quot;: &amp;quot;[the POSKey you&#039;ve just copied]&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;DEV-TEST-615&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSources&amp;quot;: [&amp;quot;All&amp;quot;],&lt;br /&gt;
    &amp;quot;OrderNumber&amp;quot;: &amp;quot;Order_01&amp;quot;,&lt;br /&gt;
    &amp;quot;RedirectUrl&amp;quot;: &amp;quot;https://example.com/&amp;quot;,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Locale&amp;quot;:&amp;quot;en-US&amp;quot;,&lt;br /&gt;
    &amp;quot;GuestCheckOut&amp;quot;: true,&lt;br /&gt;
    &amp;quot;PaymentWindow&amp;quot;:&amp;quot;00:30:00&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;DEV-TEST-01-01&amp;quot;,&lt;br /&gt;
            &amp;quot;Payee&amp;quot;: &amp;quot;[the email address associated with the Barion shop]&amp;quot;,&lt;br /&gt;
            &amp;quot;Total&amp;quot;: 100,&lt;br /&gt;
            &amp;quot;Comment&amp;quot;: &amp;quot;Test transaction&amp;quot;,&lt;br /&gt;
            &amp;quot;Items&amp;quot;: [&lt;br /&gt;
                {&lt;br /&gt;
                    &amp;quot;Name&amp;quot;: &amp;quot;Nada&amp;quot;,&lt;br /&gt;
                    &amp;quot;Description&amp;quot;: &amp;quot;Zilch&amp;quot;,&lt;br /&gt;
                    &amp;quot;Quantity&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;Unit&amp;quot;: &amp;quot;db&amp;quot;,&lt;br /&gt;
                    &amp;quot;UnitPrice&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;ItemTotal&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;SKU&amp;quot;: &amp;quot;SM-01&amp;quot;&lt;br /&gt;
                }&lt;br /&gt;
            ]&lt;br /&gt;
        }&lt;br /&gt;
    ]&lt;br /&gt;
}&amp;lt;/syntaxhighlight&amp;gt;&lt;br /&gt;
&amp;lt;blockquote&amp;gt;&lt;br /&gt;
Here&#039;s the cURL version, if that&#039;s more convenient:&lt;br /&gt;
&amp;lt;syntaxhighlight&amp;gt;&lt;br /&gt;
curl --location &#039;https://api.test.barion.com/v2/payment/start&#039; \&lt;br /&gt;
--header &#039;Content-Type: application/json&#039; \&lt;br /&gt;
--data-raw &#039;{&lt;br /&gt;
    &amp;quot;POSKey&amp;quot;: &amp;quot;5c224ce1-0f2c-4a7a-9ae7-d7c2b481cb71&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;DEV-TEST-615&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSources&amp;quot;: [&lt;br /&gt;
        &amp;quot;All&amp;quot;&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;RedirectUrl&amp;quot;: &amp;quot;https://example.com/&amp;quot;,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Locale&amp;quot;: &amp;quot;en-US&amp;quot;,&lt;br /&gt;
    &amp;quot;GuestCheckOut&amp;quot;: true,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;DEV-TEST-01-01&amp;quot;,&lt;br /&gt;
            &amp;quot;Payee&amp;quot;: &amp;quot;barionaccount@demo-merchant.shop&amp;quot;,&lt;br /&gt;
            &amp;quot;Total&amp;quot;: 100,&lt;br /&gt;
            &amp;quot;Items&amp;quot;: [&lt;br /&gt;
                {&lt;br /&gt;
                    &amp;quot;Name&amp;quot;: &amp;quot;Nada&amp;quot;,&lt;br /&gt;
                    &amp;quot;Description&amp;quot;: &amp;quot;Zilch&amp;quot;,&lt;br /&gt;
                    &amp;quot;Quantity&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;Unit&amp;quot;: &amp;quot;db&amp;quot;,&lt;br /&gt;
                    &amp;quot;UnitPrice&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;ItemTotal&amp;quot;: 1&lt;br /&gt;
                }&lt;br /&gt;
            ]&lt;br /&gt;
        }&lt;br /&gt;
    ]&lt;br /&gt;
}&#039;&lt;br /&gt;
&amp;lt;/syntaxhighlight&amp;gt;&lt;br /&gt;
&amp;lt;/blockquote&amp;gt;&lt;br /&gt;
For details on the various parameters you’re passing in the call, see [[Payment-Start-v2|the &amp;lt;code&amp;gt;Payment/Start&amp;lt;/code&amp;gt; API endpoint reference]].&lt;br /&gt;
&amp;lt;blockquote&amp;gt;&lt;br /&gt;
Step result:  The API request returns the following JSON:  &amp;lt;br /&amp;gt;&lt;br /&gt;
&amp;lt;syntaxhighlight lang=&amp;quot;json&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;PaymentId&amp;quot;: &amp;quot;ee849878c554ef118c0c001dd8b71cc5&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;DEV-TEST-615&amp;quot;,&lt;br /&gt;
    &amp;quot;Status&amp;quot;: &amp;quot;Prepared&amp;quot;,&lt;br /&gt;
    &amp;quot;QRUrl&amp;quot;: &amp;quot;https://api.test.barion.com/qr/generate?paymentId=ee849878-c554-ef11-8c0c-001dd8b71cc5&amp;amp;size=Large&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;DEV-TEST-01-01&amp;quot;,&lt;br /&gt;
            &amp;quot;TransactionId&amp;quot;: &amp;quot;ef849878c554ef118c0c001dd8b71cc5&amp;quot;,&lt;br /&gt;
            &amp;quot;Status&amp;quot;: &amp;quot;Prepared&amp;quot;,&lt;br /&gt;
            &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
            &amp;quot;TransactionTime&amp;quot;: &amp;quot;0001-01-01T00:00:00&amp;quot;,&lt;br /&gt;
            &amp;quot;RelatedId&amp;quot;: null&lt;br /&gt;
        }&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;RecurrenceResult&amp;quot;: &amp;quot;None&amp;quot;,&lt;br /&gt;
    &amp;quot;ThreeDSAuthClientData&amp;quot;: null,&lt;br /&gt;
    &amp;quot;GatewayUrl&amp;quot;: &amp;quot;https://secure.test.barion.com/Pay?Id=ee849878c554ef118c0c001dd8b71cc5&amp;quot;,&lt;br /&gt;
    &amp;quot;RedirectUrl&amp;quot;: &amp;quot;https://example.com/?paymentId=ee849878c554ef118c0c001dd8b71cc5&amp;quot;,&lt;br /&gt;
    &amp;quot;CallbackUrl&amp;quot;: &amp;quot;&amp;quot;,&lt;br /&gt;
    &amp;quot;TraceId&amp;quot;: null,&lt;br /&gt;
    &amp;quot;Errors&amp;quot;: []&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/syntaxhighlight&amp;gt;&lt;br /&gt;
&amp;lt;/blockquote&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Pay through the Barion Smart Gateway: ==&lt;br /&gt;
Go to the URL in the POST call’s &amp;lt;code&amp;gt;GatewayURL&amp;lt;/code&amp;gt; return value, and complete the purchase using the following test card details:&lt;br /&gt;
&lt;br /&gt;
* Card number: 4444 8888 8888 5559&lt;br /&gt;
* Expiration date: any future date&lt;br /&gt;
* CVC: any 3-digit number&lt;br /&gt;
&lt;br /&gt;
== Next steps ==&lt;br /&gt;
&lt;br /&gt;
* [[Going live|Go live with your Barion Shop]]&lt;br /&gt;
* [[List of API endpoints|Dive into the Barion Payment API]]&lt;br /&gt;
* [[Token payment|Set up a recurring payment/subscription]]&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4971</id>
		<title>Barion Shop Authentication</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4971"/>
		<updated>2026-11-07T08:23:02Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: Added screenshots for the Security settings&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= What is shop authentication? =&lt;br /&gt;
&lt;br /&gt;
The API endpoints related to handling a shop&#039;s payment flow are accessible using the shop&#039;s own unique API key, known as &amp;lt;i&amp;gt;POS key&amp;lt;/i&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
For a full list of such endpoints see [[List_of_API_endpoints|List of Barion API endpoints]].&lt;br /&gt;
&lt;br /&gt;
Optionally, the shop can also use an &amp;lt;i&amp;gt;HMAC key&amp;lt;/i&amp;gt; to sign its API requests and to verify the messages Barion sends to it. See [[#Message signature (HMAC)|Message signature (HMAC)]].&lt;br /&gt;
&lt;br /&gt;
= Using POS keys =&lt;br /&gt;
&lt;br /&gt;
To use an endpoint which requires shop-level authentication, pass your Barion shop&#039;s POS key as the &#039;&#039;&#039;x-pos-key&#039;&#039;&#039; header parameter.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=&amp;lt;tt&amp;gt;GET&amp;lt;/tt&amp;gt; API endpoints below v4 also accept the &amp;lt;code&amp;gt;PosKey&amp;lt;/code&amp;gt; property as a query parameter.|color=#038Ed3}}&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
An invalid key generates an &amp;lt;code&amp;gt;AuthenticationFailed&amp;lt;/code&amp;gt; error.&lt;br /&gt;
&lt;br /&gt;
= Managing POS keys =&lt;br /&gt;
&lt;br /&gt;
A POS key is automatically generated for your shop when you create it. You find your shop&#039;s current POS keys on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Security). The confirmation e-mail that was sent to you when you opened the shop also contains the key the shop had at that time.&lt;br /&gt;
&lt;br /&gt;
[[File:Annotated security steps.png]]&lt;br /&gt;
&lt;br /&gt;
[[File:POS Key.png]]&lt;br /&gt;
&lt;br /&gt;
== Changing the POS key ==&lt;br /&gt;
&lt;br /&gt;
You can replace your POS key at any time, for example if you think it has leaked. A shop can have 2 POS keys at most, and while it has two, Barion accepts both. This lets you switch without any downtime:&lt;br /&gt;
&lt;br /&gt;
# On the shop&#039;s security page, click &amp;lt;i&amp;gt;Generate new POSKey&amp;lt;/i&amp;gt;. The new key is shown as &amp;lt;i&amp;gt;New POSKey&amp;lt;/i&amp;gt;, the current one as &amp;lt;i&amp;gt;Old POSKey&amp;lt;/i&amp;gt;.&lt;br /&gt;
# Change your integration to use the new key, wherever you send the POS key. The old key keeps working in the meantime.&lt;br /&gt;
# Once all your systems use the new key, delete the old key on the security page. From that moment Barion rejects requests sent with it.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=A shop always needs a POS key, so its last key cannot be deleted. Deleting a key takes effect immediately and cannot be undone. Changing the POS key does not affect your HMAC key.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
= Message signature (HMAC) =&lt;br /&gt;
&lt;br /&gt;
A shop can have an HMAC key in addition to its POS key. While the shop has an &amp;lt;b&amp;gt;active&amp;lt;/b&amp;gt; HMAC key:&lt;br /&gt;
* every API request authenticated with the shop&#039;s POS key &amp;lt;b&amp;gt;must be signed&amp;lt;/b&amp;gt; with the HMAC key, otherwise Barion rejects it,&lt;br /&gt;
* Barion signs its responses to these requests, and&lt;br /&gt;
* Barion signs the payment IPN (callback) messages it sends to the shop.&lt;br /&gt;
&lt;br /&gt;
This lets your server verify that a message really comes from Barion and was not changed on the way, and lets Barion verify that a request really comes from your shop.&lt;br /&gt;
&lt;br /&gt;
The signature is an HMAC-SHA512 computed with the shop&#039;s HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Activating a key takes effect &amp;lt;b&amp;gt;immediately&amp;lt;/b&amp;gt;: from that moment, every unsigned or wrongly signed request of the shop is rejected, payment start included. Signature headers are ignored while the shop has no active key, so start signing your requests &amp;lt;b&amp;gt;before&amp;lt;/b&amp;gt; you activate the key.|color=#D73E48}}&lt;br /&gt;
&lt;br /&gt;
== Managing HMAC keys ==&lt;br /&gt;
&lt;br /&gt;
HMAC keys are managed on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Security).&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[File:POS Key and HMAC Keys.png]]&lt;br /&gt;
&lt;br /&gt;
* A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.&lt;br /&gt;
* A new key is created &amp;lt;b&amp;gt;inactive&amp;lt;/b&amp;gt;. Mark it as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; when your server is ready.&lt;br /&gt;
* At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.&lt;br /&gt;
* The active key cannot be deleted. Deactivate it, or activate the other key, first.&lt;br /&gt;
* The key is shown and copied as a base64 string. &amp;lt;b&amp;gt;Decode it from base64&amp;lt;/b&amp;gt; and use the resulting 64 bytes as the HMAC key.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=Keep the HMAC key on your server only, like the POS key. If you think a key is compromised, generate a new one, switch to it and delete the old one.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Signature headers ==&lt;br /&gt;
&lt;br /&gt;
Every signed request and response carries these three headers:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Header !! Content&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-timestamp&#039;&#039;&#039; || The time of signing as a Unix timestamp in seconds (UTC), e.g. &amp;lt;code&amp;gt;1760968800&amp;lt;/code&amp;gt;.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-nonce&#039;&#039;&#039; || A GUID, e.g. &amp;lt;code&amp;gt;3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&amp;lt;/code&amp;gt;. In a request it must be new for every request. In a response it is the nonce of the request being answered.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-signature-sha512&#039;&#039;&#039; || The HMAC-SHA512 of the signed text (see below), base64-encoded.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== The signed text ==&lt;br /&gt;
&lt;br /&gt;
The signature is computed over a text made of the following parts, joined with a single line feed character (&amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt;, LF, no carriage return). The text is UTF-8 encoded before signing.&lt;br /&gt;
&lt;br /&gt;
=== Requests (your API requests and Barion&#039;s IPN) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;HTTP method&#039;&#039;&#039;: in upper case, e.g. &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;path and query&#039;&#039;&#039;: the path and the query string of the URL as it appears on the request line, &#039;&#039;&#039;in lower case&#039;&#039;&#039;, e.g. &amp;lt;code&amp;gt;/v2/payment/start&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;/v2/payment/getpaymentstate?paymentid=...&amp;lt;/code&amp;gt;. The scheme, the host and the port are not part of it.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact request body, byte for byte as it is sent. The body must be UTF-8 (a leading byte order mark is ignored). For a request without a body (e.g. &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;) it is an empty string, so the text ends with the line feed after the path.&lt;br /&gt;
&lt;br /&gt;
=== Responses (Barion&#039;s answers to your signed requests) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;x-nonce&#039;&#039;&#039;: the nonce of &amp;lt;b&amp;gt;your request&amp;lt;/b&amp;gt; that the response answers. It is echoed back in the response&#039;s &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and binds the response to your request.&lt;br /&gt;
* &#039;&#039;&#039;HTTP status code&#039;&#039;&#039;: as a number, e.g. &amp;lt;code&amp;gt;200&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact response body as received.&lt;br /&gt;
&lt;br /&gt;
Responses are signed only when the request was signed correctly.&lt;br /&gt;
&lt;br /&gt;
== Signing your API requests ==&lt;br /&gt;
&lt;br /&gt;
# Generate a new GUID for &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and take the current Unix time in seconds for &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;.&lt;br /&gt;
# Build the signed text from the timestamp, the nonce, the method, the path and query (in lower case), and the exact body you are going to send.&lt;br /&gt;
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.&lt;br /&gt;
# Send the request with the &amp;lt;code&amp;gt;x-pos-key&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
&lt;br /&gt;
Barion checks that:&lt;br /&gt;
* the timestamp is within 5 minutes of the server time, in either direction,&lt;br /&gt;
* the nonce has not been used by the shop before (so a captured request cannot be replayed),&lt;br /&gt;
* the signature matches the request signed with the active key.&lt;br /&gt;
&lt;br /&gt;
== Verifying Barion&#039;s messages ==&lt;br /&gt;
&lt;br /&gt;
For a response to your request, and for a payment IPN message:&lt;br /&gt;
# Read the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
# Build the signed text: for a response with the response&#039;s status code and body, for an IPN with &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt;, the path and query of your callback URL as it was called (including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; query parameter), in lower case, and the request body.&lt;br /&gt;
# Compute the HMAC-SHA512 with your active key and compare it with &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt;. Use a constant-time comparison.&lt;br /&gt;
# Reject the message if the signature does not match. We also recommend rejecting it if the timestamp is more than a few minutes off your server time, and, for an IPN, if you have already processed its nonce.&amp;lt;br /&amp;gt;&lt;br /&gt;
== Example ==&lt;br /&gt;
&lt;br /&gt;
Signing a request in C#:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
using System;&lt;br /&gt;
using System.Security.Cryptography;&lt;br /&gt;
using System.Text;&lt;br /&gt;
&lt;br /&gt;
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)&lt;br /&gt;
{&lt;br /&gt;
    // The path and query are signed in lower case; the body is used as it is.&lt;br /&gt;
    string text = string.Join(&amp;quot;\n&amp;quot;, timestamp, nonce, method.ToUpperInvariant(), pathAndQuery.ToLowerInvariant(), body ?? &amp;quot;&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))&lt;br /&gt;
    {&lt;br /&gt;
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();&lt;br /&gt;
string nonce = Guid.NewGuid().ToString();&lt;br /&gt;
string body = &amp;quot;{\&amp;quot;PaymentRequestId\&amp;quot;:\&amp;quot;...\&amp;quot;}&amp;quot;;&lt;br /&gt;
string signature = Sign(hmacKey, timestamp, nonce, &amp;quot;POST&amp;quot;, &amp;quot;/v2/Payment/Start&amp;quot;, body);&lt;br /&gt;
&lt;br /&gt;
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Test vectors ==&lt;br /&gt;
&lt;br /&gt;
Use these known values to check your implementation. The bodies are made up and are not real requests or responses.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;HMAC key&#039;&#039;&#039; (base64): &amp;lt;code&amp;gt;AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the signed texts below, &amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt; stands for a single line feed character (LF, no carriage return). It is shown at the end of the line where it belongs; the last line has none, unless the body is empty.&lt;br /&gt;
&lt;br /&gt;
=== 1. A request with a JSON body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL:           https://api.barion.com/v2/Payment/Start&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (note that the path is in lower case, and the body is used as it is):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
POST\n&lt;br /&gt;
/v2/payment/start\n&lt;br /&gt;
{&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (118 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a504f53540a2f76322f7061796d656e742f73746172740a7b225061796d656e74526571756573744964223a226f726465722d31303031222c22546f74616c223a31302e35307d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
AMm7BeXNw0JAs8pxAhemnOQzhlWDz+o/nB85yKPim0DYSCdgpswBQFyQlhFrDwb/MrPFWlcwgDGa+DFGsNJvuQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 2. A GET request without a body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        GET&lt;br /&gt;
URL:           https://api.barion.com/v4/Payment/GetPaymentState?PaymentId=3F2B6C1E-8D4A-4B9E-9A51-0C7D2E6F1A84&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f&lt;br /&gt;
Body:          (none)&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. The path and the whole query string are in lower case, including the value of &amp;lt;code&amp;gt;PaymentId&amp;lt;/code&amp;gt;. The text ends with the line feed after the query string, because the body is empty:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f\n&lt;br /&gt;
GET\n&lt;br /&gt;
/v4/payment/getpaymentstate?paymentid=3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (127 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a39643661316630652d326237632d346333352d386531392d3561346233633264316530660a4745540a2f76342f7061796d656e742f6765747061796d656e7473746174653f7061796d656e7469643d33663262366331652d386434612d346239652d396135312d3063376432653666316138340a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
z8YFYV7YKs4OY4eVfd0BSc1LJMkbmBQRFuNXFO+KiAujB7eR1oHwicRTepgVSDqzHoHow/SDoKTdX2IpNMvB8A==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 3. A response ===&lt;br /&gt;
&lt;br /&gt;
This is Barion&#039;s answer to the request in example 1. It carries the &amp;lt;b&amp;gt;nonce of the request&amp;lt;/b&amp;gt; in its &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and it has its own timestamp.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
HTTP status:   200&lt;br /&gt;
x-timestamp:   1760968801&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. There is no method and no path in a response, only the status code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968801\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
200\n&lt;br /&gt;
{&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (120 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830310a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a3230300a7b225061796d656e744964223a223366326236633165386434613462396539613531306337643265366631613834222c22537461747573223a225072657061726564227d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
7C8tktY2Bs91dyw7L/fLKwDQCyriGiVOEvbrurn79sLkT2Q93KDVw7c/LEz4VWIqhZOpzLQbs7a6UCo5BZALyQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 4. A payment IPN message ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL called:    https://shop.example/hu/DemoClub/Callback?paymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
x-timestamp:   1760968802&lt;br /&gt;
x-nonce:       7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d&lt;br /&gt;
Body:          PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (the path is in lower case, the scheme and the host are not part of it):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968802\n&lt;br /&gt;
7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d\n&lt;br /&gt;
POST\n&lt;br /&gt;
/hu/democlub/callback?paymentid=4d924e8da6cbf11199f4001dd8b71d1a\n&lt;br /&gt;
PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (160 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830320a37623165346432612d366333662d346138622d396435302d3165326633613462356336640a504f53540a2f68752f64656d6f636c75622f63616c6c6261636b3f7061796d656e7469643d34643932346538646136636266313131393966343030316464386237316431610a5061796d656e7449643d3464393234653864613663626631313139396634303031646438623731643161&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
nwEdCk0K1LeDxLqF+4QnUgtmvl0BQPGqLUl+YawMMoJhcNXnJM9xT8JlmsNyWPwWktbJo2oy+yzx6cUMqUrRiA==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Rotating the key ==&lt;br /&gt;
&lt;br /&gt;
# Generate a second key on the security page, but do not set it as Active. The current key keeps working.&lt;br /&gt;
# Prepare your server to use the newly generated key. It should be able to accept messages signed with the new key, but still use the old key for signing requests.&lt;br /&gt;
# Mark the new key as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the security page. From that moment Barion signs with the new key and checks your requests against it. For the 24 hour change period Barion still accepts requests signed with the old key.&lt;br /&gt;
# Switch your server to use the new key for signing requests within this change period.&lt;br /&gt;
# Once your server uses the new key, we recommend that you &amp;lt;b&amp;gt;delete the old key&amp;lt;/b&amp;gt; on the security page right away. Barion then rejects requests signed with it immediately, instead of accepting them until the change period ends. Deleting it also frees a place for the next key.&lt;br /&gt;
&lt;br /&gt;
== Turning signing off ==&lt;br /&gt;
&lt;br /&gt;
Untick &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the active key. Barion stops signing its messages right away and no longer checks the signature of your requests. If your server rejects unsigned messages, it will reject Barion&#039;s IPN messages and responses too.&lt;br /&gt;
&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status &amp;lt;code&amp;gt;401&amp;lt;/code&amp;gt; and one of these errors:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Error code !! Meaning&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;MissingSignature&amp;lt;/code&amp;gt; || One or more of the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers is missing.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidNonce&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; is not a GUID.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidTimestamp&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt; is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidSignature&amp;lt;/code&amp;gt; || The signature does not match the request signed with the shop&#039;s active HMAC key.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;ReplayedRequest&amp;lt;/code&amp;gt; || A request with this &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; has already been received.&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=File:POS_Key_and_HMAC_Keys.png&amp;diff=4970</id>
		<title>File:POS Key and HMAC Keys.png</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=File:POS_Key_and_HMAC_Keys.png&amp;diff=4970"/>
		<updated>2026-11-07T08:22:09Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;Security settings containing the POS Key and HMAC Keys&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Troubleshooting&amp;diff=4969</id>
		<title>Troubleshooting</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Troubleshooting&amp;diff=4969"/>
		<updated>2026-11-07T08:18:17Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;__NOTOC__&lt;br /&gt;
{{NotificationBox|title=CHANGE|text=TLS 1.0 is no longer supported, switch to TLS 1.1 / 1.2 now, otherwise your Barion implementation will not work!|color=#FF7A3D}}&lt;br /&gt;
&lt;br /&gt;
{{PageTitle|title= Troubleshooting - list of common pitfalls}}&lt;br /&gt;
&lt;br /&gt;
Before contacting support, please run through the list of common pitfalls. This will save both you and us a lot of time. Here we go with the list.&lt;br /&gt;
&lt;br /&gt;
==Polling the server instead of using the callback ==&lt;br /&gt;
Many developers fail to implement the [[Callback_mechanism|callback mechanism]]. Instead, they either rely on faulty strategies:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|Calling GetPaymentState only when the customer is redirected to the shop &lt;br /&gt;
|This approach only works if the customer actually returns to the shop. If the user closes the browser after payment, but before returning to the shop, the merchant will not get notified about the successful payment. As a result, some developers choose to poll the server periodically. We strongly recommend using the callback.&lt;br /&gt;
|-&lt;br /&gt;
|Polling the server with GetPaymentState calls&lt;br /&gt;
|This approach floods the Barion servers with unnecessary API calls, slowing it down. It is also more complex to code and to test. We strongly recommend using the callback.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
Always rely on the callback. The Barion server retries the callback 5 times, so the chances of losing a payment is very little.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Flooding the Barion servers with unnecessary API calls may lead to suspension of the shop|color=#FF7A3D}}&lt;br /&gt;
&lt;br /&gt;
==Mixing up sandbox and live accounts ==&lt;br /&gt;
It is very easy to mix up [[sandbox|Live and Sandbox]] environments. Since the two systems are totally separated, you can have an account with the same e-mail address in both systems. Double check, if you can not log on.&lt;br /&gt;
&lt;br /&gt;
===Forgot to update POSKey to live===&lt;br /&gt;
It is very easy to mix up [[sandbox|Live and Sandbox]] environments. A very common mistake is to not update the POSKey to the Live server when going live. Same goes to URL-s.&lt;br /&gt;
&lt;br /&gt;
===Forgot to update Barion Pixel Id to live===&lt;br /&gt;
A very common mistake is leaving Barion Test Pixel Id ( BPT-xxxxxxxxxx-xx ) in the [[Barion_Pixel#Implementing_the_base_code_for_fraud_prevention|Barion Pixel base code]]. Update the Barion Pixel Id to the Live server when going live.&lt;br /&gt;
&lt;br /&gt;
==Shop not approved==&lt;br /&gt;
Log on to Barion Web App and check if your shop is approved and open. Edit your shop and send it for approval (note that you must fill in all data to be able to do this).&lt;br /&gt;
After sending the shop for approval, the Sandbox server approves the shop automatically, but the Live environment requires human approval. You will be notified about the process in e-mail.&lt;br /&gt;
&lt;br /&gt;
==Paying in your own shop==&lt;br /&gt;
If you try to pay as the owner of the shop that started the payment (meaning the payer and payee e-mail addresses are the same), you will get an error message. You cannot pay in your own shop.&lt;br /&gt;
&lt;br /&gt;
==Bank card payment with extreme low amounts==&lt;br /&gt;
Bank card payments do not work with very small amounts such as 1 HUF or 0.02 EUR. Please use the following amounts for card transactions, even when testing!&lt;br /&gt;
* CZK: 1.00 CZK or more&lt;br /&gt;
* EUR: 0.10 EUR or more&lt;br /&gt;
* HUF: 10 HUF or more&lt;br /&gt;
* USD: 0.10 USD or more&lt;br /&gt;
* PLN: 0.1 PLN or more&lt;br /&gt;
* RON: 1 RON or more&lt;br /&gt;
&amp;lt;blockquote&amp;gt;You can track the payment status and steps here: [[Payment monitor dashboard]]&amp;lt;/blockquote&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==Authentication error upon request==&lt;br /&gt;
If you have managed to avoid all problems mentioned above, yet you still receive an API response showing &#039;&#039;&#039;&#039;Authentication error&#039;&#039;&#039;&#039;, check your request JSON for errors. Broken multibyte strings or unescaped special characters can render the JSON unparseable, which prevents the Barion API from identifying your POSKey, resulting in an authentication error.&lt;br /&gt;
&lt;br /&gt;
==Firewall rejects GUID==&lt;br /&gt;
Some firewalls produce a false positive when long GUID-s travel in https requests.&lt;br /&gt;
&lt;br /&gt;
==Wrong or missing API version==&lt;br /&gt;
If you omit the version from the URL, the system assumes V1. In case of a V2 API, this will lead to an error. The correct way to call V2 API-s is &amp;lt;code&amp;gt;&amp;lt;nowiki&amp;gt;https://api.test.barion.com/v2/Payment/Start&amp;lt;/nowiki&amp;gt;&amp;lt;/code&amp;gt; on the sandbox.&lt;br /&gt;
&lt;br /&gt;
== Using deprecated or obosolete encryption methods ==&lt;br /&gt;
All communication with the Barion system must be done using TLS v1.1 or above - former encryption standards (SSLv3, TLS1.0 etc.) are not allowed!&lt;br /&gt;
== API calls fail after POS Key rotation ==&lt;br /&gt;
Check that your integration uses the new POS Key for sending requests. You can read more about POS Key rotation [[Barion Shop Authentication|here]].&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_for_Shopify&amp;diff=4968</id>
		<title>Barion for Shopify</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_for_Shopify&amp;diff=4968"/>
		<updated>2026-11-07T08:09:33Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: Updated POS Key screenshots and path&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;=[DEPRECATED] Barion for Shopify=&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=WARNING| text=As of January 6, 2025, Shopify has begun phasing out additional scripts, meaning Barion can no longer be used as a payment method for new integrations on the Shopify platform. However, existing integrations will continue to be supported by Shopify until June 30, 2026.|color=#FF0000}}&lt;br /&gt;
&lt;br /&gt;
== New to Shopify? Upgrade your business with a fully functional webshop in no time ==&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
- Bring your business online: Create an e-commerce website backed by powerful tools that help you find customers, drive sales, and manage your day-to-day&lt;br /&gt;
&lt;br /&gt;
- Make the most out of your online business: Powerful tools already integrated into Shopify shops like insights, order management, and many integrated payment solutions&lt;br /&gt;
&lt;br /&gt;
- Online payment with Barion: Make the most out of your online business by providing online payment for customers. Barion Smart Gateway has you covered&lt;br /&gt;
&lt;br /&gt;
- Payments made international: Enjoy the benefits of Barion&#039;s many features. For example multiple languages and currencies, card payments, wire transfer payment, and mobile payments&lt;br /&gt;
==Have a Shopify shop? Downgrade your payment costs with Barion==&lt;br /&gt;
&lt;br /&gt;
- Join Barion and integrate our safe, secure and cost-effective solution with your shop in a few steps and start paying less fees.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
=Onboarding steps=&lt;br /&gt;
&lt;br /&gt;
=== Register » Create a Shop ===&lt;br /&gt;
&lt;br /&gt;
# [https://secure.barion.com/Registration/Organization?isEmailLocked=False Register a Barion account for your Business]&lt;br /&gt;
# [https://www.barion.com/en/help/business/open-and-manage-a-shop/how-can-i-create-a-barion-shop-does-this-require-any-approval/ Create a Shop]&lt;br /&gt;
&lt;br /&gt;
=== Add Barion logo to your Shop&#039;s footer ===&lt;br /&gt;
&lt;br /&gt;
# [https://download.barion.com/barion/barion-smart-payment-banners.zip Get the Barion logo in multiple formats]&lt;br /&gt;
# [https://community.shopify.com/c/Shopify-Design/Adding-image-in-Supply-theme-Footer/td-p/352036 Insert them as image into your Shopify footer]&lt;br /&gt;
&lt;br /&gt;
=== Add Barion Pixel to your Shop&#039;s header ===&lt;br /&gt;
&lt;br /&gt;
# [https://docs.barion.com/Getting_started_with_the_Barion_Pixel Getting started with the Pixel]&lt;br /&gt;
# [https://docs.barion.com/Implementing_the_Base_Barion_Pixel Adding code into your Shopify shop&#039;s theme]&lt;br /&gt;
# [https://docs.barion.com/Smar_Documentation Implement Full Pixel features with our Shopify-Pixel plugin]&lt;br /&gt;
&lt;br /&gt;
=== Add Barion to your General Terms and Conditions document ===&lt;br /&gt;
&lt;br /&gt;
# The General Terms and Conditions/Terms of Purchase has a section on paying by Barion bank card.&lt;br /&gt;
# Use the language of your website: [https://www.barion.com/en/help/business/open-and-manage-a-shop/why-are-appropriate-general-terms-and-conditionsterms-of-purchase-necessary-for-the-approval-of-the-shop/ English], [https://www.barion.com/hu/ugyfelszolgalat/elfogadohely/elfogadohely-letrehozasa-es-kezelese/miert-szukseges-megfelelo-aszfvasarlasi-feltetel-az-elfogadohely-jovahagyasahoz/ Hungarian], [https://www.barion.com/sk/podpora/firmy/prijimanie-peniazi-za-nakup--barion-obchod-integracia/pre%C4%8Do-su-potrebne-spravne-vop--podmienky-nakupu-na-schvalenie// Slovakian], [https://www.barion.com/cs/podpory/firmy/p%C5%99ijimani-pen%C4%9Bz-za-nakup-%E2%80%93-integrace-barion-shopu/pro%C4%8D-jsou-t%C5%99eba-spravne-vop--obchodni-podminky-nakupu-ke-schvaleni/ Czech], [https://www.barion.com/de/support/business/erstellen-und-verwalten-einer-akzeptanzstelle/warum-sind-angemessene-agbkaufbedingungen-fur-die-genehmigung-der-akzeptanzstelle-erforderlich/ German].&lt;br /&gt;
&lt;br /&gt;
=== Maintain Shopify admin settings to enable Barion Payment Gateway ===&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT| text=The shop in Barion system must be checked and approved for a live payment method.|color=#FF7A3D}}&lt;br /&gt;
&lt;br /&gt;
==== Create a private application  ====&lt;br /&gt;
On the main admin interface click &#039;&#039;Settings&#039;&#039; at the bottom of the left side menu, then select &#039;&#039;Apps and sales channels&#039;&#039; from the left side menu.&lt;br /&gt;
Click the &#039;&#039;Develop apps&#039; button, then the &#039;&#039;Create an app&#039;&#039; button.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[File:Create_private_app_007.png|1000px]]&lt;br /&gt;
&lt;br /&gt;
Then click on &amp;quot;Create an app&amp;quot; button:&lt;br /&gt;
&lt;br /&gt;
[[File:Create_private_app_001.png|1000px]]&lt;br /&gt;
&lt;br /&gt;
Define a name and an e-mail address you wish to use:&lt;br /&gt;
&lt;br /&gt;
[[File:Create_private_app_002.png|1000px]]&lt;br /&gt;
&lt;br /&gt;
Go to your private app and click on &amp;quot;Configure Admin Api Scopes&amp;quot;:&lt;br /&gt;
&lt;br /&gt;
[[File:Create_private_app_008.png|1000px]]&lt;br /&gt;
&lt;br /&gt;
Enable the option of &amp;quot;write_orders&amp;quot; and &amp;quot;read_orders&amp;quot; under Orders:&lt;br /&gt;
&lt;br /&gt;
[[File:Create_private_app_003.png|1000px]]&lt;br /&gt;
&lt;br /&gt;
When the private app has been created successfully you need to &#039;&#039;Install the app&#039;&#039; in order to get the Shopify API key and Shopify Password.&lt;br /&gt;
&lt;br /&gt;
[[File:Shopify-newAppDevelopment-preAccessKey.png|Shopify-newAppDevelopment-preAccessKey.png]]&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Mark down both codes as they will be needed to configure your shop at https://shopify.barion.com/|color=#FF7A3D}}&lt;br /&gt;
* Shopify API key is provided in the API credentials tab, under API key and secret block. &lt;br /&gt;
* Shopify Password must be revealed first, then provided as Shopify Password. &lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[File:Shopify_key_and_password.png|Shopify_key_and_password.png]]&lt;br /&gt;
&lt;br /&gt;
==== Adding the integration code to Shopify Admin interface ====&lt;br /&gt;
&lt;br /&gt;
&amp;lt;span id=&amp;quot;april_24_update&amp;quot;&amp;gt;&amp;lt;/span&amp;gt;&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=DEPRECATION WARNING| text=Some Shopify APIs that affect the scripts in this section are no longer supported past April 1 2024. The barion.js and barion_v2.js scripts in this section have been updated to comply with the changes.|color=#FF7A3D}}&lt;br /&gt;
&lt;br /&gt;
On the main admin page click &#039;&#039;Settings&#039;&#039; at the bottom of the left side menu, then select &#039;&#039;Checkout&#039;&#039; from the left side menu and add the following code to the section &#039;&#039;Additional scripts&#039;&#039;: &lt;br /&gt;
&amp;lt;br&amp;gt;(Here you should already have the text added during Pixel installation)&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=The below steps will differ whether you create an Application for SANDBOX (see https://docs.barion.com/Sandbox) or PRODUCTION environments!|color=#FF7A3D}}&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;SANDBOX&#039;&#039;&#039; script:&lt;br /&gt;
&amp;lt;pre&amp;gt;&amp;lt;script src=&amp;quot;https://shopify.test.barion.com/js/barion/barion.js&amp;quot;&amp;gt;&amp;lt;/script&amp;gt;&lt;br /&gt;
&amp;lt;script&amp;gt;Barion.init({&lt;br /&gt;
orderId: &#039;{{ order.id }}&#039;,&lt;br /&gt;
domain: &#039;{{shop.permanent_domain}}&#039;,&lt;br /&gt;
gateway: &#039;{{order.transactions[0].gateway}}&#039;,&lt;br /&gt;
orderStatus: &#039;{{order.financial_status}}&#039;,&lt;br /&gt;
sandboxMode: true&lt;br /&gt;
})&amp;lt;/script&amp;gt;&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;PRODUCTION&#039;&#039;&#039; script:&lt;br /&gt;
&amp;lt;pre&amp;gt;&amp;lt;script src=&amp;quot;https://shopify.barion.com/js/barion/barion.js&amp;quot;&amp;gt;&amp;lt;/script&amp;gt;&lt;br /&gt;
&amp;lt;script&amp;gt;Barion.init({&lt;br /&gt;
orderId: &#039;{{ order.id }}&#039;,&lt;br /&gt;
domain: &#039;{{shop.permanent_domain}}&#039;,&lt;br /&gt;
gateway: &#039;{{order.transactions[0].gateway}}&#039;,&lt;br /&gt;
orderStatus: &#039;{{order.financial_status}}&#039;&lt;br /&gt;
})&amp;lt;/script&amp;gt;&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;PRODUCTION script(alternative version):&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
If you experience issues with the redirection to the Barion Smart Gateway, you can use this code snippet instead of the production version above. It is important to place this script at the beginning of the &#039;&#039;Order status page&#039;&#039; section. &lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Be careful, this script uses reload on the &#039;&#039;Thank you&#039;&#039; page, so it can confuse your measuring.|color=#FF7A3D}}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&amp;lt;script src=&amp;quot;https://shopify.barion.com/js/barion/barion_v2.js&amp;quot;&amp;gt;&amp;lt;/script&amp;gt;&lt;br /&gt;
&amp;lt;script&amp;gt;Barion.init({&lt;br /&gt;
orderId: &#039;{{ order.id }}&#039;,&lt;br /&gt;
domain: &#039;{{shop.permanent_domain}}&#039;,&lt;br /&gt;
gateway: &#039;{{order.transactions[0].gateway}}&#039;,&lt;br /&gt;
orderStatus: &#039;{{order.financial_status}}&#039;&lt;br /&gt;
})&amp;lt;/script&amp;gt;&amp;lt;/pre&amp;gt;[[File:Settings checkout additional-scripts.png]]&lt;br /&gt;
&lt;br /&gt;
== Add Barion as a payment method on the Shopify Admin interface ==&lt;br /&gt;
&lt;br /&gt;
On Shopify admin page click &#039;&#039;Settings&#039;&#039; at the bottom of the left side menu, then select &#039;&#039;Payments&#039;&#039; from the left side menu.&lt;br /&gt;
From the &#039;&#039;Manual payment methods&#039; area click the &#039;&#039;Add manual payment method&#039;&#039; button and choose &#039;&#039;Create custom payment method&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
[[File:Shopify_Admin_Add_Custom_payment_method.png|400px]]&lt;br /&gt;
&lt;br /&gt;
Provide the following details:&lt;br /&gt;
&lt;br /&gt;
* Custom payment method name: &#039;&#039;&#039;Barion Payments&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
* Additional details: after making an order you will be directed to the billing interface of Barion.&lt;br /&gt;
&lt;br /&gt;
After you have provided everything, click to &#039;&#039;Active&#039;&#039; button.&lt;br /&gt;
&lt;br /&gt;
[[File:Create_manual_payment_002.png|1000px]]&lt;br /&gt;
&lt;br /&gt;
== Get verified ==&lt;br /&gt;
&lt;br /&gt;
# [https://www.barion.com/en/help/business/raise-the-limits-of-your-business-account/ Get verified], &lt;br /&gt;
# [https://www.barion.com/en/help/business/raise-the-limits-of-your-business-account/required-documents-for-video-identification/ The documents you need]&lt;br /&gt;
&lt;br /&gt;
== Link your Shopify shop with Barion ==&lt;br /&gt;
You need to create the link between Shopify and Barion at https://shopify.barion.com/&lt;br /&gt;
&amp;lt;strong&amp;gt;&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=In order to be able to log in here, kindly open a ticket at https://secure.barion.com/Remark and request that Barion API shall be accessed with username and password as well.&lt;br /&gt;
Also note, that your shop must be open to be able to save these settings!|color=#FF7A3D}}&amp;lt;/strong&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Once logged in you shall see the following landing page:&amp;lt;br&amp;gt;&lt;br /&gt;
[[File:shopify.barion.com_-_main_page.png]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;Shopify domain&#039;&#039;&#039; - you shall type here your Shopify domain that you see in your browser address bar. &lt;br /&gt;
** i.e.: &#039;&#039;&amp;lt;nowiki&amp;gt;https://myfirstbarionshop.myshopify.com/&amp;lt;/nowiki&amp;gt;&#039;&#039;  should end up here as &#039;&#039;myfirstbarionshop.myshopify.com&#039;&#039;&lt;br /&gt;
For following two fields you need the values you saved from [https://docs.barion.com/Barion_for_Shopify#Create_a_private_application Create a private application] step.&lt;br /&gt;
* &#039;&#039;&#039;Shopify API Key&#039;&#039;&#039; - Here you need the &#039;&#039;API key and secret key&#039;&#039; value.&lt;br /&gt;
* &#039;&#039;&#039;Shopify password&#039;&#039;&#039; - Here you need the &#039;&#039;Admin API access token&#039;&#039; value.&lt;br /&gt;
* &#039;&#039;&#039;Barion Secret key (POSKey)&#039;&#039;&#039; - You can find the POS Key of your Barion shop as described [https://docs.barion.com/Barion_for_Shopify#Retrieving_the_POS_key here]&lt;br /&gt;
* &#039;&#039;&#039;Currency&#039;&#039;&#039; - Add the currency that will be used in your shop transactions. &lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Please bear in mind that the number of digits accepted may differ by currency. At the moment we accept two digits for CZK, EUR, USD and zero digits for HUF. This applies to any discount logic that reduce the sum by some percent. The final amount within Shopify must comply with the digits restrictions!|color=#FF7A3D}}&lt;br /&gt;
* &#039;&#039;&#039;Language&#039;&#039;&#039; - this will determine the language Barion Payment Gateway is shown the your clients&lt;br /&gt;
&lt;br /&gt;
=== Retrieving the POS key ===&lt;br /&gt;
&lt;br /&gt;
To get your Barion Shop&#039;s Secret key (POSKey), go to [https://secure.barion.com/Shop your Barion shops] click on the &#039;&#039;Actions&#039;&#039; and &#039;&#039;Security&#039;&#039; to find your key. Copy it to the Shopify plugins Settings page, set there the primary currency and the shops language.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
[[File:Annotated security steps.png]]&lt;br /&gt;
&lt;br /&gt;
[[File:POS Key.png]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Once done, do not forget to save your entry!&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
= TROUBLESHOOTING =&lt;br /&gt;
&lt;br /&gt;
== Error messages and actions ==&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;The store is closed in the Barion system, payment is not allowed.&#039;&#039;&#039;&lt;br /&gt;
In this case your Barion Shop is not &#039;&#039;&#039;approved&#039;&#039;&#039; yet. If the POSKey you used is for the right shop, you have to wait until it is approved.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Application not installed&#039;&#039;&#039;&lt;br /&gt;
# The javascript code you pasted from here to the Shopify Checkout settings / Additional scripts field is most likely wrong. Keep in mind that the script is a bit different for the test/sandbox and for production.&lt;br /&gt;
# Order API rights were not set to read/write for the private app&lt;br /&gt;
# The plugin (shopify.barion.com) is set to a different domain than the shop itself (has to match the domain that is visible on the checkout page).&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Making_a_test_payment&amp;diff=4967</id>
		<title>Making a test payment</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Making_a_test_payment&amp;diff=4967"/>
		<updated>2026-11-07T08:05:42Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: Updated POS Key screenshots and path&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{PageTitle|title=Making a test payment}}&lt;br /&gt;
{| style=&amp;quot;margin-left:2em;&amp;quot; align=&amp;quot;right&amp;quot;&lt;br /&gt;
| __TOC__&lt;br /&gt;
|}&lt;br /&gt;
Get a feel for how Barion works by using the Barion Gateway API to&lt;br /&gt;
&lt;br /&gt;
# set up a payment for the Barion shop you’ve created, and&lt;br /&gt;
# settle the payment with some test money from your Barion Wallet.&lt;br /&gt;
&lt;br /&gt;
== Prerequisites ==&lt;br /&gt;
&lt;br /&gt;
* Completing [[Creating a shop|the first part of this tutorial]].&lt;br /&gt;
* An API testing tool such as [https://www.postman.com/downloads/ Postman]&lt;br /&gt;
&lt;br /&gt;
== Make a test payment using the Barion API ==&lt;br /&gt;
&lt;br /&gt;
1. Log in to [https://secure.test.barion.com to your Barion shop].&lt;br /&gt;
&lt;br /&gt;
2. Click through to Shops&amp;amp;#x3E;Actions&amp;amp;#x3E;Security&amp;amp;#x3E;Secret Key (POSKey), and copy the value to the clipboard.  &lt;br /&gt;
[[File:Annotated security steps.png|left|frame|&#039;&#039;Finding your shop’s POSKey&#039;&#039;]]&lt;br /&gt;
[[File:POS Key.png|left|frame]]&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=All Barion API endpoints accept standard HTTP1.1 GET or POST method requests, but always one or the other only. Calling an endpoint with the incorrect HTTP method returns a JSON error message.|color=#1798DB}}&lt;br /&gt;
&lt;br /&gt;
3. Start the Postman Desktop agent, and make a POST call to &amp;lt;code&amp;gt;https://api.test.barion.com/v2/payment/start&amp;lt;/code&amp;gt;, passing the following JSON in the request body:  Replace the &amp;lt;code&amp;gt;POSKey&amp;lt;/code&amp;gt; and the &amp;lt;code&amp;gt;Transactions&amp;lt;/code&amp;gt;/&amp;lt;code&amp;gt;Payee&amp;lt;/code&amp;gt; as indicated.&lt;br /&gt;
&amp;lt;syntaxhighlight lang=&amp;quot;json&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;POSKey&amp;quot;: &amp;quot;[the POSKey you&#039;ve just copied]&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;DEV-TEST-615&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSources&amp;quot;: [&amp;quot;All&amp;quot;],&lt;br /&gt;
    &amp;quot;OrderNumber&amp;quot;: &amp;quot;Order_01&amp;quot;,&lt;br /&gt;
    &amp;quot;RedirectUrl&amp;quot;: &amp;quot;https://example.com/&amp;quot;,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Locale&amp;quot;:&amp;quot;en-US&amp;quot;,&lt;br /&gt;
    &amp;quot;GuestCheckOut&amp;quot;: true,&lt;br /&gt;
    &amp;quot;PaymentWindow&amp;quot;:&amp;quot;00:30:00&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;DEV-TEST-01-01&amp;quot;,&lt;br /&gt;
            &amp;quot;Payee&amp;quot;: &amp;quot;[the email address associated with the Barion shop]&amp;quot;,&lt;br /&gt;
            &amp;quot;Total&amp;quot;: 100,&lt;br /&gt;
            &amp;quot;Comment&amp;quot;: &amp;quot;Test transaction&amp;quot;,&lt;br /&gt;
            &amp;quot;Items&amp;quot;: [&lt;br /&gt;
                {&lt;br /&gt;
                    &amp;quot;Name&amp;quot;: &amp;quot;Nada&amp;quot;,&lt;br /&gt;
                    &amp;quot;Description&amp;quot;: &amp;quot;Zilch&amp;quot;,&lt;br /&gt;
                    &amp;quot;Quantity&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;Unit&amp;quot;: &amp;quot;db&amp;quot;,&lt;br /&gt;
                    &amp;quot;UnitPrice&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;ItemTotal&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;SKU&amp;quot;: &amp;quot;SM-01&amp;quot;&lt;br /&gt;
                }&lt;br /&gt;
            ]&lt;br /&gt;
        }&lt;br /&gt;
    ]&lt;br /&gt;
}&amp;lt;/syntaxhighlight&amp;gt;&lt;br /&gt;
&amp;lt;blockquote&amp;gt;&lt;br /&gt;
Here&#039;s the cURL version, if that&#039;s more convenient:&lt;br /&gt;
&amp;lt;syntaxhighlight&amp;gt;&lt;br /&gt;
curl --location &#039;https://api.test.barion.com/v2/payment/start&#039; \&lt;br /&gt;
--header &#039;Content-Type: application/json&#039; \&lt;br /&gt;
--data-raw &#039;{&lt;br /&gt;
    &amp;quot;POSKey&amp;quot;: &amp;quot;5c224ce1-0f2c-4a7a-9ae7-d7c2b481cb71&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;DEV-TEST-615&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSources&amp;quot;: [&lt;br /&gt;
        &amp;quot;All&amp;quot;&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;RedirectUrl&amp;quot;: &amp;quot;https://example.com/&amp;quot;,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Locale&amp;quot;: &amp;quot;en-US&amp;quot;,&lt;br /&gt;
    &amp;quot;GuestCheckOut&amp;quot;: true,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;DEV-TEST-01-01&amp;quot;,&lt;br /&gt;
            &amp;quot;Payee&amp;quot;: &amp;quot;barionaccount@demo-merchant.shop&amp;quot;,&lt;br /&gt;
            &amp;quot;Total&amp;quot;: 100,&lt;br /&gt;
            &amp;quot;Items&amp;quot;: [&lt;br /&gt;
                {&lt;br /&gt;
                    &amp;quot;Name&amp;quot;: &amp;quot;Nada&amp;quot;,&lt;br /&gt;
                    &amp;quot;Description&amp;quot;: &amp;quot;Zilch&amp;quot;,&lt;br /&gt;
                    &amp;quot;Quantity&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;Unit&amp;quot;: &amp;quot;db&amp;quot;,&lt;br /&gt;
                    &amp;quot;UnitPrice&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;ItemTotal&amp;quot;: 1&lt;br /&gt;
                }&lt;br /&gt;
            ]&lt;br /&gt;
        }&lt;br /&gt;
    ]&lt;br /&gt;
}&#039;&lt;br /&gt;
&amp;lt;/syntaxhighlight&amp;gt;&lt;br /&gt;
&amp;lt;/blockquote&amp;gt;&lt;br /&gt;
For details on the various parameters you’re passing in the call, see [[Payment-Start-v2|the &amp;lt;code&amp;gt;Payment/Start&amp;lt;/code&amp;gt; API endpoint reference]].&lt;br /&gt;
&amp;lt;blockquote&amp;gt;&lt;br /&gt;
Step result:  The API request returns the following JSON:  &amp;lt;br /&amp;gt;&lt;br /&gt;
&amp;lt;syntaxhighlight lang=&amp;quot;json&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;PaymentId&amp;quot;: &amp;quot;ee849878c554ef118c0c001dd8b71cc5&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;DEV-TEST-615&amp;quot;,&lt;br /&gt;
    &amp;quot;Status&amp;quot;: &amp;quot;Prepared&amp;quot;,&lt;br /&gt;
    &amp;quot;QRUrl&amp;quot;: &amp;quot;https://api.test.barion.com/qr/generate?paymentId=ee849878-c554-ef11-8c0c-001dd8b71cc5&amp;amp;size=Large&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;DEV-TEST-01-01&amp;quot;,&lt;br /&gt;
            &amp;quot;TransactionId&amp;quot;: &amp;quot;ef849878c554ef118c0c001dd8b71cc5&amp;quot;,&lt;br /&gt;
            &amp;quot;Status&amp;quot;: &amp;quot;Prepared&amp;quot;,&lt;br /&gt;
            &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
            &amp;quot;TransactionTime&amp;quot;: &amp;quot;0001-01-01T00:00:00&amp;quot;,&lt;br /&gt;
            &amp;quot;RelatedId&amp;quot;: null&lt;br /&gt;
        }&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;RecurrenceResult&amp;quot;: &amp;quot;None&amp;quot;,&lt;br /&gt;
    &amp;quot;ThreeDSAuthClientData&amp;quot;: null,&lt;br /&gt;
    &amp;quot;GatewayUrl&amp;quot;: &amp;quot;https://secure.test.barion.com/Pay?Id=ee849878c554ef118c0c001dd8b71cc5&amp;quot;,&lt;br /&gt;
    &amp;quot;RedirectUrl&amp;quot;: &amp;quot;https://example.com/?paymentId=ee849878c554ef118c0c001dd8b71cc5&amp;quot;,&lt;br /&gt;
    &amp;quot;CallbackUrl&amp;quot;: &amp;quot;&amp;quot;,&lt;br /&gt;
    &amp;quot;TraceId&amp;quot;: null,&lt;br /&gt;
    &amp;quot;Errors&amp;quot;: []&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/syntaxhighlight&amp;gt;&lt;br /&gt;
&amp;lt;/blockquote&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Pay through the Barion Smart Gateway: ==&lt;br /&gt;
Go to the URL in the POST call’s &amp;lt;code&amp;gt;GatewayURL&amp;lt;/code&amp;gt; return value, and complete the purchase using the following test card details:&lt;br /&gt;
&lt;br /&gt;
* Card number: 4444 8888 8888 5559&lt;br /&gt;
* Expiration date: any future date&lt;br /&gt;
* CVC: any 3-digit number&lt;br /&gt;
&lt;br /&gt;
== Next steps ==&lt;br /&gt;
&lt;br /&gt;
* [[Going live|Go live with your Barion Shop]]&lt;br /&gt;
* [[List of API endpoints|Dive into the Barion Payment API]]&lt;br /&gt;
* [[Token payment|Set up a recurring payment/subscription]]&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=File:POS_Key.png&amp;diff=4966</id>
		<title>File:POS Key.png</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=File:POS_Key.png&amp;diff=4966"/>
		<updated>2026-11-07T08:04:44Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;POS Key screen&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=File:Annotated_security_steps.png&amp;diff=4965</id>
		<title>File:Annotated security steps.png</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=File:Annotated_security_steps.png&amp;diff=4965"/>
		<updated>2026-11-07T08:00:44Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;Steps for finding the Security menu&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4964</id>
		<title>Barion Shop Authentication</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4964"/>
		<updated>2026-11-06T11:14:48Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: Added back POSKey rotation&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= What is shop authentication? =&lt;br /&gt;
&lt;br /&gt;
The API endpoints related to handling a shop&#039;s payment flow are accessible using the shop&#039;s own unique API key, known as &amp;lt;i&amp;gt;POS key&amp;lt;/i&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
For a full list of such endpoints see [[List_of_API_endpoints|List of Barion API endpoints]].&lt;br /&gt;
&lt;br /&gt;
Optionally, the shop can also use an &amp;lt;i&amp;gt;HMAC key&amp;lt;/i&amp;gt; to sign its API requests and to verify the messages Barion sends to it. See [[#Message signature (HMAC)|Message signature (HMAC)]].&lt;br /&gt;
&lt;br /&gt;
= Using POS keys =&lt;br /&gt;
&lt;br /&gt;
To use an endpoint which requires shop-level authentication, pass your Barion shop&#039;s POS key as the &#039;&#039;&#039;x-pos-key&#039;&#039;&#039; header parameter.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=&amp;lt;tt&amp;gt;GET&amp;lt;/tt&amp;gt; API endpoints below v4 also accept the &amp;lt;code&amp;gt;PosKey&amp;lt;/code&amp;gt; property as a query parameter.|color=#038Ed3}}&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
An invalid key generates an &amp;lt;code&amp;gt;AuthenticationFailed&amp;lt;/code&amp;gt; error.&lt;br /&gt;
&lt;br /&gt;
= Managing POS keys =&lt;br /&gt;
&lt;br /&gt;
A POS key is automatically generated for your shop when you create it. You find your shop&#039;s current POS keys on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Security). The confirmation e-mail that was sent to you when you opened the shop also contains the key the shop had at that time.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=The test and live environment are completely separate environments, you need to create different shops. Make sure that you use the POSkey and not the public key:&lt;br /&gt;
&lt;br /&gt;
[[File:Poskey.jpg]] |color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Changing the POS key ==&lt;br /&gt;
&lt;br /&gt;
You can replace your POS key at any time, for example if you think it has leaked. A shop can have 2 POS keys at most, and while it has two, Barion accepts both. This lets you switch without any downtime:&lt;br /&gt;
&lt;br /&gt;
# On the shop&#039;s security page, click &amp;lt;i&amp;gt;Generate new POSKey&amp;lt;/i&amp;gt;. The new key is shown as &amp;lt;i&amp;gt;New POSKey&amp;lt;/i&amp;gt;, the current one as &amp;lt;i&amp;gt;Old POSKey&amp;lt;/i&amp;gt;.&lt;br /&gt;
# Change your integration to use the new key, wherever you send the POS key. The old key keeps working in the meantime.&lt;br /&gt;
# Once all your systems use the new key, delete the old key on the security page. From that moment Barion rejects requests sent with it.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=A shop always needs a POS key, so its last key cannot be deleted. Deleting a key takes effect immediately and cannot be undone. Changing the POS key does not affect your HMAC key.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
= Message signature (HMAC) =&lt;br /&gt;
&lt;br /&gt;
A shop can have an HMAC key in addition to its POS key. While the shop has an &amp;lt;b&amp;gt;active&amp;lt;/b&amp;gt; HMAC key:&lt;br /&gt;
* every API request authenticated with the shop&#039;s POS key &amp;lt;b&amp;gt;must be signed&amp;lt;/b&amp;gt; with the HMAC key, otherwise Barion rejects it,&lt;br /&gt;
* Barion signs its responses to these requests, and&lt;br /&gt;
* Barion signs the payment IPN (callback) messages it sends to the shop.&lt;br /&gt;
&lt;br /&gt;
This lets your server verify that a message really comes from Barion and was not changed on the way, and lets Barion verify that a request really comes from your shop.&lt;br /&gt;
&lt;br /&gt;
The signature is an HMAC-SHA512 computed with the shop&#039;s HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Activating a key takes effect &amp;lt;b&amp;gt;immediately&amp;lt;/b&amp;gt;: from that moment, every unsigned or wrongly signed request of the shop is rejected, payment start included. Signature headers are ignored while the shop has no active key, so start signing your requests &amp;lt;b&amp;gt;before&amp;lt;/b&amp;gt; you activate the key.|color=#D73E48}}&lt;br /&gt;
&lt;br /&gt;
== Managing HMAC keys ==&lt;br /&gt;
&lt;br /&gt;
HMAC keys are managed on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Security).&lt;br /&gt;
&lt;br /&gt;
* A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.&lt;br /&gt;
* A new key is created &amp;lt;b&amp;gt;inactive&amp;lt;/b&amp;gt;. Mark it as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; when your server is ready.&lt;br /&gt;
* At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.&lt;br /&gt;
* The active key cannot be deleted. Deactivate it, or activate the other key, first.&lt;br /&gt;
* The key is shown and copied as a base64 string. &amp;lt;b&amp;gt;Decode it from base64&amp;lt;/b&amp;gt; and use the resulting 64 bytes as the HMAC key.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=Keep the HMAC key on your server only, like the POS key. If you think a key is compromised, generate a new one, switch to it and delete the old one.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Signature headers ==&lt;br /&gt;
&lt;br /&gt;
Every signed request and response carries these three headers:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Header !! Content&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-timestamp&#039;&#039;&#039; || The time of signing as a Unix timestamp in seconds (UTC), e.g. &amp;lt;code&amp;gt;1760968800&amp;lt;/code&amp;gt;.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-nonce&#039;&#039;&#039; || A GUID, e.g. &amp;lt;code&amp;gt;3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&amp;lt;/code&amp;gt;. In a request it must be new for every request. In a response it is the nonce of the request being answered.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-signature-sha512&#039;&#039;&#039; || The HMAC-SHA512 of the signed text (see below), base64-encoded.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== The signed text ==&lt;br /&gt;
&lt;br /&gt;
The signature is computed over a text made of the following parts, joined with a single line feed character (&amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt;, LF, no carriage return). The text is UTF-8 encoded before signing.&lt;br /&gt;
&lt;br /&gt;
=== Requests (your API requests and Barion&#039;s IPN) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;HTTP method&#039;&#039;&#039;: in upper case, e.g. &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;path and query&#039;&#039;&#039;: the path and the query string of the URL as it appears on the request line, &#039;&#039;&#039;in lower case&#039;&#039;&#039;, e.g. &amp;lt;code&amp;gt;/v2/payment/start&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;/v2/payment/getpaymentstate?paymentid=...&amp;lt;/code&amp;gt;. The scheme, the host and the port are not part of it.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact request body, byte for byte as it is sent. The body must be UTF-8 (a leading byte order mark is ignored). For a request without a body (e.g. &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;) it is an empty string, so the text ends with the line feed after the path.&lt;br /&gt;
&lt;br /&gt;
=== Responses (Barion&#039;s answers to your signed requests) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;x-nonce&#039;&#039;&#039;: the nonce of &amp;lt;b&amp;gt;your request&amp;lt;/b&amp;gt; that the response answers. It is echoed back in the response&#039;s &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and binds the response to your request.&lt;br /&gt;
* &#039;&#039;&#039;HTTP status code&#039;&#039;&#039;: as a number, e.g. &amp;lt;code&amp;gt;200&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact response body as received.&lt;br /&gt;
&lt;br /&gt;
Responses are signed only when the request was signed correctly.&lt;br /&gt;
&lt;br /&gt;
== Signing your API requests ==&lt;br /&gt;
&lt;br /&gt;
# Generate a new GUID for &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and take the current Unix time in seconds for &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;.&lt;br /&gt;
# Build the signed text from the timestamp, the nonce, the method, the path and query (in lower case), and the exact body you are going to send.&lt;br /&gt;
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.&lt;br /&gt;
# Send the request with the &amp;lt;code&amp;gt;x-pos-key&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
&lt;br /&gt;
Barion checks that:&lt;br /&gt;
* the timestamp is within 5 minutes of the server time, in either direction,&lt;br /&gt;
* the nonce has not been used by the shop before (so a captured request cannot be replayed),&lt;br /&gt;
* the signature matches the request signed with the active key.&lt;br /&gt;
&lt;br /&gt;
== Verifying Barion&#039;s messages ==&lt;br /&gt;
&lt;br /&gt;
For a response to your request, and for a payment IPN message:&lt;br /&gt;
# Read the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
# Build the signed text: for a response with the response&#039;s status code and body, for an IPN with &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt;, the path and query of your callback URL as it was called (including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; query parameter), in lower case, and the request body.&lt;br /&gt;
# Compute the HMAC-SHA512 with your active key and compare it with &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt;. Use a constant-time comparison.&lt;br /&gt;
# Reject the message if the signature does not match. We also recommend rejecting it if the timestamp is more than a few minutes off your server time, and, for an IPN, if you have already processed its nonce.&amp;lt;br /&amp;gt;&lt;br /&gt;
== Example ==&lt;br /&gt;
&lt;br /&gt;
Signing a request in C#:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
using System;&lt;br /&gt;
using System.Security.Cryptography;&lt;br /&gt;
using System.Text;&lt;br /&gt;
&lt;br /&gt;
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)&lt;br /&gt;
{&lt;br /&gt;
    // The path and query are signed in lower case; the body is used as it is.&lt;br /&gt;
    string text = string.Join(&amp;quot;\n&amp;quot;, timestamp, nonce, method.ToUpperInvariant(), pathAndQuery.ToLowerInvariant(), body ?? &amp;quot;&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))&lt;br /&gt;
    {&lt;br /&gt;
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();&lt;br /&gt;
string nonce = Guid.NewGuid().ToString();&lt;br /&gt;
string body = &amp;quot;{\&amp;quot;PaymentRequestId\&amp;quot;:\&amp;quot;...\&amp;quot;}&amp;quot;;&lt;br /&gt;
string signature = Sign(hmacKey, timestamp, nonce, &amp;quot;POST&amp;quot;, &amp;quot;/v2/Payment/Start&amp;quot;, body);&lt;br /&gt;
&lt;br /&gt;
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Test vectors ==&lt;br /&gt;
&lt;br /&gt;
Use these known values to check your implementation. The bodies are made up and are not real requests or responses.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;HMAC key&#039;&#039;&#039; (base64): &amp;lt;code&amp;gt;AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the signed texts below, &amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt; stands for a single line feed character (LF, no carriage return). It is shown at the end of the line where it belongs; the last line has none, unless the body is empty.&lt;br /&gt;
&lt;br /&gt;
=== 1. A request with a JSON body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL:           https://api.barion.com/v2/Payment/Start&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (note that the path is in lower case, and the body is used as it is):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
POST\n&lt;br /&gt;
/v2/payment/start\n&lt;br /&gt;
{&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (118 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a504f53540a2f76322f7061796d656e742f73746172740a7b225061796d656e74526571756573744964223a226f726465722d31303031222c22546f74616c223a31302e35307d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
AMm7BeXNw0JAs8pxAhemnOQzhlWDz+o/nB85yKPim0DYSCdgpswBQFyQlhFrDwb/MrPFWlcwgDGa+DFGsNJvuQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 2. A GET request without a body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        GET&lt;br /&gt;
URL:           https://api.barion.com/v4/Payment/GetPaymentState?PaymentId=3F2B6C1E-8D4A-4B9E-9A51-0C7D2E6F1A84&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f&lt;br /&gt;
Body:          (none)&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. The path and the whole query string are in lower case, including the value of &amp;lt;code&amp;gt;PaymentId&amp;lt;/code&amp;gt;. The text ends with the line feed after the query string, because the body is empty:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f\n&lt;br /&gt;
GET\n&lt;br /&gt;
/v4/payment/getpaymentstate?paymentid=3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (127 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a39643661316630652d326237632d346333352d386531392d3561346233633264316530660a4745540a2f76342f7061796d656e742f6765747061796d656e7473746174653f7061796d656e7469643d33663262366331652d386434612d346239652d396135312d3063376432653666316138340a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
z8YFYV7YKs4OY4eVfd0BSc1LJMkbmBQRFuNXFO+KiAujB7eR1oHwicRTepgVSDqzHoHow/SDoKTdX2IpNMvB8A==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 3. A response ===&lt;br /&gt;
&lt;br /&gt;
This is Barion&#039;s answer to the request in example 1. It carries the &amp;lt;b&amp;gt;nonce of the request&amp;lt;/b&amp;gt; in its &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and it has its own timestamp.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
HTTP status:   200&lt;br /&gt;
x-timestamp:   1760968801&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. There is no method and no path in a response, only the status code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968801\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
200\n&lt;br /&gt;
{&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (120 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830310a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a3230300a7b225061796d656e744964223a223366326236633165386434613462396539613531306337643265366631613834222c22537461747573223a225072657061726564227d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
7C8tktY2Bs91dyw7L/fLKwDQCyriGiVOEvbrurn79sLkT2Q93KDVw7c/LEz4VWIqhZOpzLQbs7a6UCo5BZALyQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 4. A payment IPN message ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL called:    https://shop.example/hu/DemoClub/Callback?paymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
x-timestamp:   1760968802&lt;br /&gt;
x-nonce:       7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d&lt;br /&gt;
Body:          PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (the path is in lower case, the scheme and the host are not part of it):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968802\n&lt;br /&gt;
7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d\n&lt;br /&gt;
POST\n&lt;br /&gt;
/hu/democlub/callback?paymentid=4d924e8da6cbf11199f4001dd8b71d1a\n&lt;br /&gt;
PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (160 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830320a37623165346432612d366333662d346138622d396435302d3165326633613462356336640a504f53540a2f68752f64656d6f636c75622f63616c6c6261636b3f7061796d656e7469643d34643932346538646136636266313131393966343030316464386237316431610a5061796d656e7449643d3464393234653864613663626631313139396634303031646438623731643161&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
nwEdCk0K1LeDxLqF+4QnUgtmvl0BQPGqLUl+YawMMoJhcNXnJM9xT8JlmsNyWPwWktbJo2oy+yzx6cUMqUrRiA==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Rotating the key ==&lt;br /&gt;
&lt;br /&gt;
# Generate a second key on the security page, but do not set it as Active. The current key keeps working.&lt;br /&gt;
# Prepare your server to use the newly generated key. It should be able to accept messages signed with the new key, but still use the old key for signing requests.&lt;br /&gt;
# Mark the new key as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the security page. From that moment Barion signs with the new key and checks your requests against it. For the 24 hour change period Barion still accepts requests signed with the old key.&lt;br /&gt;
# Switch your server to use the new key for signing requests within this change period.&lt;br /&gt;
# Once your server uses the new key, we recommend that you &amp;lt;b&amp;gt;delete the old key&amp;lt;/b&amp;gt; on the security page right away. Barion then rejects requests signed with it immediately, instead of accepting them until the change period ends. Deleting it also frees a place for the next key.&lt;br /&gt;
&lt;br /&gt;
== Turning signing off ==&lt;br /&gt;
&lt;br /&gt;
Untick &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the active key. Barion stops signing its messages right away and no longer checks the signature of your requests. If your server rejects unsigned messages, it will reject Barion&#039;s IPN messages and responses too.&lt;br /&gt;
&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status &amp;lt;code&amp;gt;401&amp;lt;/code&amp;gt; and one of these errors:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Error code !! Meaning&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;MissingSignature&amp;lt;/code&amp;gt; || One or more of the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers is missing.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidNonce&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; is not a GUID.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidTimestamp&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt; is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidSignature&amp;lt;/code&amp;gt; || The signature does not match the request signed with the shop&#039;s active HMAC key.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;ReplayedRequest&amp;lt;/code&amp;gt; || A request with this &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; has already been received.&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4961</id>
		<title>Barion Shop Authentication</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4961"/>
		<updated>2026-11-05T09:29:08Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= What is shop authentication? =&lt;br /&gt;
&lt;br /&gt;
The API endpoints related to handling a shop&#039;s payment flow are accessible using the shop&#039;s own unique API key, known as &amp;lt;i&amp;gt;POS key&amp;lt;/i&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
For a full list of such endpoints see [[List_of_API_endpoints|List of Barion API endpoints]].&lt;br /&gt;
&lt;br /&gt;
Optionally, the shop can also use an &amp;lt;i&amp;gt;HMAC key&amp;lt;/i&amp;gt; to sign its API requests and to verify the messages Barion sends to it. See [[#Message signature (HMAC)|Message signature (HMAC)]].&lt;br /&gt;
&lt;br /&gt;
= Using POS keys =&lt;br /&gt;
&lt;br /&gt;
To use an endpoint which requires shop-level authentication, pass your Barion shop&#039;s POS key as the &#039;&#039;&#039;x-pos-key&#039;&#039;&#039; header parameter.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=&amp;lt;tt&amp;gt;GET&amp;lt;/tt&amp;gt; API endpoints below v4 also accept the &amp;lt;code&amp;gt;PosKey&amp;lt;/code&amp;gt; property as a query parameter.|color=#038Ed3}}&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
An invalid key generates an &amp;lt;code&amp;gt;AuthenticationFailed&amp;lt;/code&amp;gt; error.&lt;br /&gt;
&lt;br /&gt;
= Managing POS keys =&lt;br /&gt;
&lt;br /&gt;
A POS key is automatically generated for your shop when you create it. You find your shop&#039;s current POS keys on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Security). The confirmation e-mail that was sent to you when you opened the shop also contains the key the shop had at that time.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=The test and live environment are completely separate environments, you need to create different shops. Make sure that you use the POSkey and not the public key:&lt;br /&gt;
&lt;br /&gt;
[[File:Poskey.jpg]] |color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Changing the POS key ==&lt;br /&gt;
&lt;br /&gt;
You can replace your POS key at any time, for example if you think it has leaked. A shop can have 2 POS keys at most, and while it has two, Barion accepts both. This lets you switch without any downtime:&lt;br /&gt;
&lt;br /&gt;
# On the shop&#039;s security page, click &amp;lt;i&amp;gt;Generate new POSKey&amp;lt;/i&amp;gt;. The new key is shown as &amp;lt;i&amp;gt;New POSKey&amp;lt;/i&amp;gt;, the current one as &amp;lt;i&amp;gt;Old POSKey&amp;lt;/i&amp;gt;.&lt;br /&gt;
# Change your integration to use the new key, wherever you send the POS key. The old key keeps working in the meantime.&lt;br /&gt;
# Once all your systems use the new key, delete the old key on the security page. From that moment Barion rejects requests sent with it.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=A shop always needs a POS key, so its last key cannot be deleted. Deleting a key takes effect immediately and cannot be undone. Changing the POS key does not affect your HMAC key.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
= Message signature (HMAC) =&lt;br /&gt;
&lt;br /&gt;
A shop can have an HMAC key in addition to its POS key. While the shop has an &amp;lt;b&amp;gt;active&amp;lt;/b&amp;gt; HMAC key:&lt;br /&gt;
* every API request authenticated with the shop&#039;s POS key &amp;lt;b&amp;gt;must be signed&amp;lt;/b&amp;gt; with the HMAC key, otherwise Barion rejects it,&lt;br /&gt;
* Barion signs its responses to these requests, and&lt;br /&gt;
* Barion signs the payment IPN (callback) messages it sends to the shop.&lt;br /&gt;
&lt;br /&gt;
This lets your server verify that a message really comes from Barion and was not changed on the way, and lets Barion verify that a request really comes from your shop.&lt;br /&gt;
&lt;br /&gt;
The signature is an HMAC-SHA512 computed with the shop&#039;s HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Activating a key takes effect &amp;lt;b&amp;gt;immediately&amp;lt;/b&amp;gt;: from that moment, every unsigned or wrongly signed request of the shop is rejected, payment start included. Signature headers are ignored while the shop has no active key, so start signing your requests &amp;lt;b&amp;gt;before&amp;lt;/b&amp;gt; you activate the key.|color=#D73E48}}&lt;br /&gt;
&lt;br /&gt;
== Managing HMAC keys ==&lt;br /&gt;
&lt;br /&gt;
HMAC keys are managed on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Security).&lt;br /&gt;
&lt;br /&gt;
* A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.&lt;br /&gt;
* A new key is created &amp;lt;b&amp;gt;inactive&amp;lt;/b&amp;gt;. Mark it as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; when your server is ready.&lt;br /&gt;
* At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.&lt;br /&gt;
* The active key cannot be deleted. Deactivate it, or activate the other key, first.&lt;br /&gt;
* The key is shown and copied as a base64 string. &amp;lt;b&amp;gt;Decode it from base64&amp;lt;/b&amp;gt; and use the resulting 64 bytes as the HMAC key.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=Keep the HMAC key on your server only, like the POS key. If you think a key is compromised, generate a new one, switch to it and delete the old one.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Signature headers ==&lt;br /&gt;
&lt;br /&gt;
Every signed request and response carries these three headers:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Header !! Content&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-timestamp&#039;&#039;&#039; || The time of signing as a Unix timestamp in seconds (UTC), e.g. &amp;lt;code&amp;gt;1760968800&amp;lt;/code&amp;gt;.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-nonce&#039;&#039;&#039; || A GUID, e.g. &amp;lt;code&amp;gt;3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&amp;lt;/code&amp;gt;. In a request it must be new for every request. In a response it is the nonce of the request being answered.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-signature-sha512&#039;&#039;&#039; || The HMAC-SHA512 of the signed text (see below), base64-encoded.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== The signed text ==&lt;br /&gt;
&lt;br /&gt;
The signature is computed over a text made of the following parts, joined with a single line feed character (&amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt;, LF, no carriage return). The text is UTF-8 encoded before signing.&lt;br /&gt;
&lt;br /&gt;
=== Requests (your API requests and Barion&#039;s IPN) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;HTTP method&#039;&#039;&#039;: in upper case, e.g. &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;path and query&#039;&#039;&#039;: the path and the query string of the URL as it appears on the request line, &#039;&#039;&#039;in lower case&#039;&#039;&#039;, e.g. &amp;lt;code&amp;gt;/v2/payment/start&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;/v2/payment/getpaymentstate?paymentid=...&amp;lt;/code&amp;gt;. The scheme, the host and the port are not part of it.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact request body, byte for byte as it is sent. The body must be UTF-8 (a leading byte order mark is ignored). For a request without a body (e.g. &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;) it is an empty string, so the text ends with the line feed after the path.&lt;br /&gt;
&lt;br /&gt;
=== Responses (Barion&#039;s answers to your signed requests) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;x-nonce&#039;&#039;&#039;: the nonce of &amp;lt;b&amp;gt;your request&amp;lt;/b&amp;gt; that the response answers. It is echoed back in the response&#039;s &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and binds the response to your request.&lt;br /&gt;
* &#039;&#039;&#039;HTTP status code&#039;&#039;&#039;: as a number, e.g. &amp;lt;code&amp;gt;200&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact response body as received.&lt;br /&gt;
&lt;br /&gt;
Responses are signed only when the request was signed correctly.&lt;br /&gt;
&lt;br /&gt;
== Signing your API requests ==&lt;br /&gt;
&lt;br /&gt;
# Generate a new GUID for &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and take the current Unix time in seconds for &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;.&lt;br /&gt;
# Build the signed text from the timestamp, the nonce, the method, the path and query (in lower case), and the exact body you are going to send.&lt;br /&gt;
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.&lt;br /&gt;
# Send the request with the &amp;lt;code&amp;gt;x-pos-key&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
&lt;br /&gt;
Barion checks that:&lt;br /&gt;
* the timestamp is within 5 minutes of the server time, in either direction,&lt;br /&gt;
* the nonce has not been used by the shop before (so a captured request cannot be replayed),&lt;br /&gt;
* the signature matches the request signed with the active key.&lt;br /&gt;
&lt;br /&gt;
== Verifying Barion&#039;s messages ==&lt;br /&gt;
&lt;br /&gt;
For a response to your request, and for a payment IPN message:&lt;br /&gt;
# Read the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
# Build the signed text: for a response with the response&#039;s status code and body, for an IPN with &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt;, the path and query of your callback URL as it was called (including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; query parameter), in lower case, and the request body.&lt;br /&gt;
# Compute the HMAC-SHA512 with your active key and compare it with &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt;. Use a constant-time comparison.&lt;br /&gt;
# Reject the message if the signature does not match. We also recommend rejecting it if the timestamp is more than a few minutes off your server time, and, for an IPN, if you have already processed its nonce.&amp;lt;br /&amp;gt;&lt;br /&gt;
== Example ==&lt;br /&gt;
&lt;br /&gt;
Signing a request in C#:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
using System;&lt;br /&gt;
using System.Security.Cryptography;&lt;br /&gt;
using System.Text;&lt;br /&gt;
&lt;br /&gt;
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)&lt;br /&gt;
{&lt;br /&gt;
    // The path and query are signed in lower case; the body is used as it is.&lt;br /&gt;
    string text = string.Join(&amp;quot;\n&amp;quot;, timestamp, nonce, method.ToUpperInvariant(), pathAndQuery.ToLowerInvariant(), body ?? &amp;quot;&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))&lt;br /&gt;
    {&lt;br /&gt;
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();&lt;br /&gt;
string nonce = Guid.NewGuid().ToString();&lt;br /&gt;
string body = &amp;quot;{\&amp;quot;PaymentRequestId\&amp;quot;:\&amp;quot;...\&amp;quot;}&amp;quot;;&lt;br /&gt;
string signature = Sign(hmacKey, timestamp, nonce, &amp;quot;POST&amp;quot;, &amp;quot;/v2/Payment/Start&amp;quot;, body);&lt;br /&gt;
&lt;br /&gt;
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Test vectors ==&lt;br /&gt;
&lt;br /&gt;
Use these known values to check your implementation. The bodies are made up and are not real requests or responses.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;HMAC key&#039;&#039;&#039; (base64): &amp;lt;code&amp;gt;AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the signed texts below, &amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt; stands for a single line feed character (LF, no carriage return). It is shown at the end of the line where it belongs; the last line has none, unless the body is empty.&lt;br /&gt;
&lt;br /&gt;
=== 1. A request with a JSON body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL:           https://api.barion.com/v2/Payment/Start&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (note that the path is in lower case, and the body is used as it is):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
POST\n&lt;br /&gt;
/v2/payment/start\n&lt;br /&gt;
{&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (118 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a504f53540a2f76322f7061796d656e742f73746172740a7b225061796d656e74526571756573744964223a226f726465722d31303031222c22546f74616c223a31302e35307d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
AMm7BeXNw0JAs8pxAhemnOQzhlWDz+o/nB85yKPim0DYSCdgpswBQFyQlhFrDwb/MrPFWlcwgDGa+DFGsNJvuQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 2. A GET request without a body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        GET&lt;br /&gt;
URL:           https://api.barion.com/v4/Payment/GetPaymentState?PaymentId=3F2B6C1E-8D4A-4B9E-9A51-0C7D2E6F1A84&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f&lt;br /&gt;
Body:          (none)&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. The path and the whole query string are in lower case, including the value of &amp;lt;code&amp;gt;PaymentId&amp;lt;/code&amp;gt;. The text ends with the line feed after the query string, because the body is empty:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f\n&lt;br /&gt;
GET\n&lt;br /&gt;
/v4/payment/getpaymentstate?paymentid=3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (127 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a39643661316630652d326237632d346333352d386531392d3561346233633264316530660a4745540a2f76342f7061796d656e742f6765747061796d656e7473746174653f7061796d656e7469643d33663262366331652d386434612d346239652d396135312d3063376432653666316138340a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
z8YFYV7YKs4OY4eVfd0BSc1LJMkbmBQRFuNXFO+KiAujB7eR1oHwicRTepgVSDqzHoHow/SDoKTdX2IpNMvB8A==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 3. A response ===&lt;br /&gt;
&lt;br /&gt;
This is Barion&#039;s answer to the request in example 1. It carries the &amp;lt;b&amp;gt;nonce of the request&amp;lt;/b&amp;gt; in its &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and it has its own timestamp.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
HTTP status:   200&lt;br /&gt;
x-timestamp:   1760968801&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. There is no method and no path in a response, only the status code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968801\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
200\n&lt;br /&gt;
{&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (120 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830310a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a3230300a7b225061796d656e744964223a223366326236633165386434613462396539613531306337643265366631613834222c22537461747573223a225072657061726564227d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
7C8tktY2Bs91dyw7L/fLKwDQCyriGiVOEvbrurn79sLkT2Q93KDVw7c/LEz4VWIqhZOpzLQbs7a6UCo5BZALyQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 4. A payment IPN message ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL called:    https://shop.example/hu/DemoClub/Callback?paymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
x-timestamp:   1760968802&lt;br /&gt;
x-nonce:       7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d&lt;br /&gt;
Body:          PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (the path is in lower case, the scheme and the host are not part of it):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968802\n&lt;br /&gt;
7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d\n&lt;br /&gt;
POST\n&lt;br /&gt;
/hu/democlub/callback?paymentid=4d924e8da6cbf11199f4001dd8b71d1a\n&lt;br /&gt;
PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (160 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830320a37623165346432612d366333662d346138622d396435302d3165326633613462356336640a504f53540a2f68752f64656d6f636c75622f63616c6c6261636b3f7061796d656e7469643d34643932346538646136636266313131393966343030316464386237316431610a5061796d656e7449643d3464393234653864613663626631313139396634303031646438623731643161&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
nwEdCk0K1LeDxLqF+4QnUgtmvl0BQPGqLUl+YawMMoJhcNXnJM9xT8JlmsNyWPwWktbJo2oy+yzx6cUMqUrRiA==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Rotating the key ==&lt;br /&gt;
&lt;br /&gt;
# Generate a second key on the security page, but do not set it as Active. The current key keeps working.&lt;br /&gt;
# Prepare your server to use the newly generated key. It should be able to accept messages signed with the new key, but still use the old key for signing requests.&lt;br /&gt;
# Mark the new key as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the security page. From that moment Barion signs with the new key and checks your requests against it. For the 24 hour change period Barion still accepts requests signed with the old key.&lt;br /&gt;
# Switch your server to use the new key for signing requests within this change period.&lt;br /&gt;
# Once your server uses the new key, we recommend that you &amp;lt;b&amp;gt;delete the old key&amp;lt;/b&amp;gt; on the security page right away. Barion then rejects requests signed with it immediately, instead of accepting them until the change period ends. Deleting it also frees a place for the next key.&lt;br /&gt;
&lt;br /&gt;
== Turning signing off ==&lt;br /&gt;
&lt;br /&gt;
Untick &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the active key. Barion stops signing its messages right away and no longer checks the signature of your requests. If your server rejects unsigned messages, it will reject Barion&#039;s IPN messages and responses too.&lt;br /&gt;
&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status &amp;lt;code&amp;gt;401&amp;lt;/code&amp;gt; and one of these errors:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Error code !! Meaning&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;MissingSignature&amp;lt;/code&amp;gt; || One or more of the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers is missing.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidNonce&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; is not a GUID.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidTimestamp&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt; is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidSignature&amp;lt;/code&amp;gt; || The signature does not match the request signed with the shop&#039;s active HMAC key.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;ReplayedRequest&amp;lt;/code&amp;gt; || A request with this &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; has already been received.&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4958</id>
		<title>Barion Shop Authentication</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4958"/>
		<updated>2026-10-21T08:28:31Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= What is shop authentication? =&lt;br /&gt;
&lt;br /&gt;
The API endpoints related to handling a shop&#039;s payment flow are accessible using the shop&#039;s own unique API key, known as &amp;lt;i&amp;gt;POS key&amp;lt;/i&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
For a full list of such endpoints see [[List_of_API_endpoints|List of Barion API endpoints]].&lt;br /&gt;
&lt;br /&gt;
Optionally, the shop can also use an &amp;lt;i&amp;gt;HMAC key&amp;lt;/i&amp;gt; to sign its API requests and to verify the messages Barion sends to it. See [[#Message signature (HMAC)|Message signature (HMAC)]].&lt;br /&gt;
&lt;br /&gt;
= Using POS keys =&lt;br /&gt;
&lt;br /&gt;
To use an endpoint which requires shop-level authentication, pass your Barion shop&#039;s POS key as the &#039;&#039;&#039;x-pos-key&#039;&#039;&#039; header parameter.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=&amp;lt;tt&amp;gt;GET&amp;lt;/tt&amp;gt; API endpoints below v4 also accept the &amp;lt;code&amp;gt;PosKey&amp;lt;/code&amp;gt; property as a query parameter.|color=#038Ed3}}&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
An invalid key generates an &amp;lt;code&amp;gt;AuthenticationFailed&amp;lt;/code&amp;gt; error.&lt;br /&gt;
&lt;br /&gt;
= Managing POS keys =&lt;br /&gt;
&lt;br /&gt;
A POS key is automatically generated for your shop when you create it, and cannot be changed later. To obtain it, either&lt;br /&gt;
* get the key from the confirmation e-mail that was sent to you when you opened the shop, or&lt;br /&gt;
* go to the shop&#039;s detail page on the [https://secure.barion.com Barion secure site] and use the &amp;lt;i&amp;gt;Secret key&amp;lt;/i&amp;gt; value (Shops -&amp;gt; Actions -&amp;gt; Details)&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=The test and live environment are completely separate environments, you need to create different shops. Make sure that you use the POSkey and not the public key:&lt;br /&gt;
&lt;br /&gt;
[[File:Poskey.jpg]] |color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
= Message signature (HMAC) =&lt;br /&gt;
&lt;br /&gt;
A shop can have an HMAC key in addition to its POS key. While the shop has an &amp;lt;b&amp;gt;active&amp;lt;/b&amp;gt; HMAC key:&lt;br /&gt;
* every API request authenticated with the shop&#039;s POS key &amp;lt;b&amp;gt;must be signed&amp;lt;/b&amp;gt; with the HMAC key, otherwise Barion rejects it,&lt;br /&gt;
* Barion signs its responses to these requests, and&lt;br /&gt;
* Barion signs the payment IPN (callback) messages it sends to the shop.&lt;br /&gt;
&lt;br /&gt;
This lets your server verify that a message really comes from Barion and was not changed on the way, and lets Barion verify that a request really comes from your shop.&lt;br /&gt;
&lt;br /&gt;
The signature is an HMAC-SHA512 computed with the shop&#039;s HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Activating a key takes effect &amp;lt;b&amp;gt;immediately&amp;lt;/b&amp;gt;: from that moment, every unsigned or wrongly signed request of the shop is rejected, payment start included. Signature headers are ignored while the shop has no active key, so start signing your requests &amp;lt;b&amp;gt;before&amp;lt;/b&amp;gt; you activate the key.|color=#D73E48}}&lt;br /&gt;
&lt;br /&gt;
== Managing HMAC keys ==&lt;br /&gt;
&lt;br /&gt;
HMAC keys are managed on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Settings -&amp;gt; Security -&amp;gt; Manage).&lt;br /&gt;
&lt;br /&gt;
* A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.&lt;br /&gt;
* A new key is created &amp;lt;b&amp;gt;inactive&amp;lt;/b&amp;gt;. Mark it as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; when your server is ready.&lt;br /&gt;
* At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.&lt;br /&gt;
* The active key cannot be deleted. Deactivate it, or activate the other key, first.&lt;br /&gt;
* The key is shown and copied as a base64 string. &amp;lt;b&amp;gt;Decode it from base64&amp;lt;/b&amp;gt; and use the resulting 64 bytes as the HMAC key.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=Keep the HMAC key on your server only, like the POS key. If you think a key is compromised, generate a new one, switch to it and delete the old one.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Signature headers ==&lt;br /&gt;
&lt;br /&gt;
Every signed request and response carries these three headers:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Header !! Content&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-timestamp&#039;&#039;&#039; || The time of signing as a Unix timestamp in seconds (UTC), e.g. &amp;lt;code&amp;gt;1760968800&amp;lt;/code&amp;gt;.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-nonce&#039;&#039;&#039; || A GUID, e.g. &amp;lt;code&amp;gt;3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&amp;lt;/code&amp;gt;. In a request it must be new for every request. In a response it is the nonce of the request being answered.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-signature-sha512&#039;&#039;&#039; || The HMAC-SHA512 of the signed text (see below), base64-encoded.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== The signed text ==&lt;br /&gt;
&lt;br /&gt;
The signature is computed over a text made of the following parts, joined with a single line feed character (&amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt;, LF, no carriage return). The text is UTF-8 encoded before signing.&lt;br /&gt;
&lt;br /&gt;
=== Requests (your API requests and Barion&#039;s IPN) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;HTTP method&#039;&#039;&#039;: in upper case, e.g. &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;path and query&#039;&#039;&#039;: the path and the query string of the URL as it appears on the request line, &#039;&#039;&#039;in lower case&#039;&#039;&#039;, e.g. &amp;lt;code&amp;gt;/v2/payment/start&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;/v4/payment/getpaymentstate?paymentid=...&amp;lt;/code&amp;gt;. The scheme, the host and the port are not part of it.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact request body, byte for byte as it is sent. The body must be UTF-8 (a leading byte order mark is ignored). For a request without a body (e.g. &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;) it is an empty string, so the text ends with the line feed after the path.&lt;br /&gt;
&lt;br /&gt;
=== Responses (Barion&#039;s answers to your signed requests) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;x-nonce&#039;&#039;&#039;: the nonce of &amp;lt;b&amp;gt;your request&amp;lt;/b&amp;gt; that the response answers. It is echoed back in the response&#039;s &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and binds the response to your request.&lt;br /&gt;
* &#039;&#039;&#039;HTTP status code&#039;&#039;&#039;: as a number, e.g. &amp;lt;code&amp;gt;200&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact response body as received.&lt;br /&gt;
&lt;br /&gt;
Responses are signed only when the request was signed correctly.&lt;br /&gt;
&lt;br /&gt;
== Signing your API requests ==&lt;br /&gt;
&lt;br /&gt;
# Generate a new GUID for &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and take the current Unix time in seconds for &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;.&lt;br /&gt;
# Build the signed text from the timestamp, the nonce, the method, the path and query (in lower case), and the exact body you are going to send.&lt;br /&gt;
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.&lt;br /&gt;
# Send the request with the &amp;lt;code&amp;gt;x-pos-key&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
&lt;br /&gt;
Barion checks that:&lt;br /&gt;
* the timestamp is within 5 minutes of the server time, in either direction,&lt;br /&gt;
* the nonce has not been used by the shop before (so a captured request cannot be replayed),&lt;br /&gt;
* the signature matches the request signed with the active key.&lt;br /&gt;
&lt;br /&gt;
== Verifying Barion&#039;s messages ==&lt;br /&gt;
&lt;br /&gt;
For a response to your request, and for a payment IPN message:&lt;br /&gt;
# Read the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
# Build the signed text: for a response with the response&#039;s status code and body, for an IPN with &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt;, the path and query of your callback URL as it was called (including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; query parameter), in lower case, and the request body.&lt;br /&gt;
# Compute the HMAC-SHA512 with your active key and compare it with &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt;. Use a constant-time comparison.&lt;br /&gt;
# Reject the message if the signature does not match. We also recommend rejecting it if the timestamp is more than a few minutes off your server time, and, for an IPN, if you have already processed its nonce.&amp;lt;br /&amp;gt;&lt;br /&gt;
== Example ==&lt;br /&gt;
&lt;br /&gt;
Signing a request in C#:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
using System;&lt;br /&gt;
using System.Security.Cryptography;&lt;br /&gt;
using System.Text;&lt;br /&gt;
&lt;br /&gt;
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)&lt;br /&gt;
{&lt;br /&gt;
    // The path and query are signed in lower case; the body is used as it is.&lt;br /&gt;
    string text = string.Join(&amp;quot;\n&amp;quot;, timestamp, nonce, method.ToUpperInvariant(), pathAndQuery.ToLowerInvariant(), body ?? &amp;quot;&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))&lt;br /&gt;
    {&lt;br /&gt;
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();&lt;br /&gt;
string nonce = Guid.NewGuid().ToString();&lt;br /&gt;
string body = &amp;quot;{\&amp;quot;PaymentRequestId\&amp;quot;:\&amp;quot;...\&amp;quot;}&amp;quot;;&lt;br /&gt;
string signature = Sign(hmacKey, timestamp, nonce, &amp;quot;POST&amp;quot;, &amp;quot;/v2/Payment/Start&amp;quot;, body);&lt;br /&gt;
&lt;br /&gt;
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Test vectors ==&lt;br /&gt;
&lt;br /&gt;
Use these known values to check your implementation. The bodies are made up and are not real requests or responses.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;HMAC key&#039;&#039;&#039; (base64): &amp;lt;code&amp;gt;AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the signed texts below, &amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt; stands for a single line feed character (LF, no carriage return). It is shown at the end of the line where it belongs; the last line has none, unless the body is empty.&lt;br /&gt;
&lt;br /&gt;
=== 1. A request with a JSON body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL:           https://api.barion.com/v2/Payment/Start&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (note that the path is in lower case, and the body is used as it is):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
POST\n&lt;br /&gt;
/v2/payment/start\n&lt;br /&gt;
{&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (118 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a504f53540a2f76322f7061796d656e742f73746172740a7b225061796d656e74526571756573744964223a226f726465722d31303031222c22546f74616c223a31302e35307d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
AMm7BeXNw0JAs8pxAhemnOQzhlWDz+o/nB85yKPim0DYSCdgpswBQFyQlhFrDwb/MrPFWlcwgDGa+DFGsNJvuQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 2. A GET request without a body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        GET&lt;br /&gt;
URL:           https://api.barion.com/v4/Payment/GetPaymentState?PaymentId=3F2B6C1E-8D4A-4B9E-9A51-0C7D2E6F1A84&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f&lt;br /&gt;
Body:          (none)&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. The path and the whole query string are in lower case, including the value of &amp;lt;code&amp;gt;PaymentId&amp;lt;/code&amp;gt;. The text ends with the line feed after the query string, because the body is empty:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f\n&lt;br /&gt;
GET\n&lt;br /&gt;
/v4/payment/getpaymentstate?paymentid=3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (127 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a39643661316630652d326237632d346333352d386531392d3561346233633264316530660a4745540a2f76342f7061796d656e742f6765747061796d656e7473746174653f7061796d656e7469643d33663262366331652d386434612d346239652d396135312d3063376432653666316138340a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
z8YFYV7YKs4OY4eVfd0BSc1LJMkbmBQRFuNXFO+KiAujB7eR1oHwicRTepgVSDqzHoHow/SDoKTdX2IpNMvB8A==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 3. A response ===&lt;br /&gt;
&lt;br /&gt;
This is Barion&#039;s answer to the request in example 1. It carries the &amp;lt;b&amp;gt;nonce of the request&amp;lt;/b&amp;gt; in its &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and it has its own timestamp.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
HTTP status:   200&lt;br /&gt;
x-timestamp:   1760968801&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. There is no method and no path in a response, only the status code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968801\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
200\n&lt;br /&gt;
{&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (120 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830310a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a3230300a7b225061796d656e744964223a223366326236633165386434613462396539613531306337643265366631613834222c22537461747573223a225072657061726564227d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
7C8tktY2Bs91dyw7L/fLKwDQCyriGiVOEvbrurn79sLkT2Q93KDVw7c/LEz4VWIqhZOpzLQbs7a6UCo5BZALyQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 4. A payment IPN message ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL called:    https://shop.example/hu/DemoClub/Callback?paymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
x-timestamp:   1760968802&lt;br /&gt;
x-nonce:       7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d&lt;br /&gt;
Body:          PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (the path is in lower case, the scheme and the host are not part of it):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968802\n&lt;br /&gt;
7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d\n&lt;br /&gt;
POST\n&lt;br /&gt;
/hu/democlub/callback?paymentid=4d924e8da6cbf11199f4001dd8b71d1a\n&lt;br /&gt;
PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (160 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830320a37623165346432612d366333662d346138622d396435302d3165326633613462356336640a504f53540a2f68752f64656d6f636c75622f63616c6c6261636b3f7061796d656e7469643d34643932346538646136636266313131393966343030316464386237316431610a5061796d656e7449643d3464393234653864613663626631313139396634303031646438623731643161&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
nwEdCk0K1LeDxLqF+4QnUgtmvl0BQPGqLUl+YawMMoJhcNXnJM9xT8JlmsNyWPwWktbJo2oy+yzx6cUMqUrRiA==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Rotating the key ==&lt;br /&gt;
&lt;br /&gt;
# Generate a second key on the security page, but do not set it as Active. The current key keeps working.&lt;br /&gt;
# Prepare your server to use the newly generated key. It should be able to accept messages signed with the new key, but still use the old key for signing requests.&lt;br /&gt;
# Mark the new key as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the security page. From that moment Barion signs with the new key and checks your requests against it. For the 24 hour change period Barion still accepts requests signed with the old key.&lt;br /&gt;
# Switch your server to use the new key for signing requests within this change period.&lt;br /&gt;
# Once your server uses the new key, we recommend that you &amp;lt;b&amp;gt;delete the old key&amp;lt;/b&amp;gt; on the security page right away. Barion then rejects requests signed with it immediately, instead of accepting them until the change period ends. Deleting it also frees a place for the next key.&lt;br /&gt;
&lt;br /&gt;
== Turning signing off ==&lt;br /&gt;
&lt;br /&gt;
Untick &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the active key. Barion stops signing its messages right away and no longer checks the signature of your requests. If your server rejects unsigned messages, it will reject Barion&#039;s IPN messages and responses too.&lt;br /&gt;
&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status &amp;lt;code&amp;gt;401&amp;lt;/code&amp;gt; and one of these errors:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Error code !! Meaning&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;MissingSignature&amp;lt;/code&amp;gt; || One or more of the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers is missing.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidNonce&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; is not a GUID.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidTimestamp&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt; is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidSignature&amp;lt;/code&amp;gt; || The signature does not match the request signed with the shop&#039;s active HMAC key.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;ReplayedRequest&amp;lt;/code&amp;gt; || A request with this &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; has already been received.&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4957</id>
		<title>Barion Shop Authentication</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4957"/>
		<updated>2026-10-21T08:23:25Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= What is shop authentication? =&lt;br /&gt;
&lt;br /&gt;
The API endpoints related to handling a shop&#039;s payment flow are accessible using the shop&#039;s own unique API key, known as &amp;lt;i&amp;gt;POS key&amp;lt;/i&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
For a full list of such endpoints see [[List_of_API_endpoints|List of Barion API endpoints]].&lt;br /&gt;
&lt;br /&gt;
Optionally, the shop can also use an &amp;lt;i&amp;gt;HMAC key&amp;lt;/i&amp;gt; to sign its API requests and to verify the messages Barion sends to it. See [[#Message signature (HMAC)|Message signature (HMAC)]].&lt;br /&gt;
&lt;br /&gt;
= Using POS keys =&lt;br /&gt;
&lt;br /&gt;
To use an endpoint which requires shop-level authentication, pass your Barion shop&#039;s POS key as the &#039;&#039;&#039;x-pos-key&#039;&#039;&#039; header parameter.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=&amp;lt;tt&amp;gt;GET&amp;lt;/tt&amp;gt; API endpoints below v4 also accept the &amp;lt;code&amp;gt;PosKey&amp;lt;/code&amp;gt; property as a query parameter.|color=#038Ed3}}&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
An invalid key generates an &amp;lt;code&amp;gt;AuthenticationFailed&amp;lt;/code&amp;gt; error.&lt;br /&gt;
&lt;br /&gt;
= Managing POS keys =&lt;br /&gt;
&lt;br /&gt;
A POS key is automatically generated for your shop when you create it, and cannot be changed later. To obtain it, either&lt;br /&gt;
* get the key from the confirmation e-mail that was sent to you when you opened the shop, or&lt;br /&gt;
* go to the shop&#039;s detail page on the [https://secure.barion.com Barion secure site] and use the &amp;lt;i&amp;gt;Secret key&amp;lt;/i&amp;gt; value (Shops -&amp;gt; Actions -&amp;gt; Details)&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=The test and live environment are completely separate environments, you need to create different shops. Make sure that you use the POSkey and not the public key:&lt;br /&gt;
&lt;br /&gt;
[[File:Poskey.jpg]] |color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
= Message signature (HMAC) =&lt;br /&gt;
&lt;br /&gt;
A shop can have an HMAC key in addition to its POS key. While the shop has an &amp;lt;b&amp;gt;active&amp;lt;/b&amp;gt; HMAC key:&lt;br /&gt;
* every API request authenticated with the shop&#039;s POS key &amp;lt;b&amp;gt;must be signed&amp;lt;/b&amp;gt; with the HMAC key, otherwise Barion rejects it,&lt;br /&gt;
* Barion signs its responses to these requests, and&lt;br /&gt;
* Barion signs the payment IPN (callback) messages it sends to the shop.&lt;br /&gt;
&lt;br /&gt;
This lets your server verify that a message really comes from Barion and was not changed on the way, and lets Barion verify that a request really comes from your shop.&lt;br /&gt;
&lt;br /&gt;
The signature is an HMAC-SHA512 computed with the shop&#039;s HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Activating a key takes effect &amp;lt;b&amp;gt;immediately&amp;lt;/b&amp;gt;: from that moment, every unsigned or wrongly signed request of the shop is rejected, payment start included. Signature headers are ignored while the shop has no active key, so start signing your requests &amp;lt;b&amp;gt;before&amp;lt;/b&amp;gt; you activate the key.|color=#D73E48}}&lt;br /&gt;
&lt;br /&gt;
== Managing HMAC keys ==&lt;br /&gt;
&lt;br /&gt;
HMAC keys are managed on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Settings -&amp;gt; Security -&amp;gt; Manage).&lt;br /&gt;
&lt;br /&gt;
* A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.&lt;br /&gt;
* A new key is created &amp;lt;b&amp;gt;inactive&amp;lt;/b&amp;gt;. Mark it as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; when your server is ready.&lt;br /&gt;
* At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.&lt;br /&gt;
* The active key cannot be deleted. Deactivate it, or activate the other key, first.&lt;br /&gt;
* The key is shown and copied as a base64 string. &amp;lt;b&amp;gt;Decode it from base64&amp;lt;/b&amp;gt; and use the resulting 64 bytes as the HMAC key.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=Keep the HMAC key on your server only, like the POS key. If you think a key is compromised, generate a new one, switch to it and delete the old one.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Signature headers ==&lt;br /&gt;
&lt;br /&gt;
Every signed request and response carries these three headers:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Header !! Content&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-timestamp&#039;&#039;&#039; || The time of signing as a Unix timestamp in seconds (UTC), e.g. &amp;lt;code&amp;gt;1760968800&amp;lt;/code&amp;gt;.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-nonce&#039;&#039;&#039; || A GUID, e.g. &amp;lt;code&amp;gt;3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&amp;lt;/code&amp;gt;. In a request it must be new for every request. In a response it is the nonce of the request being answered.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-signature-sha512&#039;&#039;&#039; || The HMAC-SHA512 of the signed text (see below), base64-encoded.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== The signed text ==&lt;br /&gt;
&lt;br /&gt;
The signature is computed over a text made of the following parts, joined with a single line feed character (&amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt;, LF, no carriage return). The text is UTF-8 encoded before signing.&lt;br /&gt;
&lt;br /&gt;
=== Requests (your API requests and Barion&#039;s IPN) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;HTTP method&#039;&#039;&#039;: in upper case, e.g. &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;path and query&#039;&#039;&#039;: the path and the query string of the URL as it appears on the request line, &#039;&#039;&#039;in lower case&#039;&#039;&#039;, e.g. &amp;lt;code&amp;gt;/v2/payment/start&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;/v4/payment/getpaymentstate?paymentid=...&amp;lt;/code&amp;gt;. The scheme, the host and the port are not part of it.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact request body, byte for byte as it is sent. The body must be UTF-8 (a leading byte order mark is ignored). For a request without a body (e.g. &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;) it is an empty string, so the text ends with the line feed after the path.&lt;br /&gt;
&lt;br /&gt;
=== Responses (Barion&#039;s answers to your signed requests) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;x-nonce&#039;&#039;&#039;: the nonce of &amp;lt;b&amp;gt;your request&amp;lt;/b&amp;gt; that the response answers. It is echoed back in the response&#039;s &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and binds the response to your request.&lt;br /&gt;
* &#039;&#039;&#039;HTTP status code&#039;&#039;&#039;: as a number, e.g. &amp;lt;code&amp;gt;200&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact response body as received.&lt;br /&gt;
&lt;br /&gt;
Responses are signed only when the request was signed correctly.&lt;br /&gt;
&lt;br /&gt;
== Signing your API requests ==&lt;br /&gt;
&lt;br /&gt;
# Generate a new GUID for &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and take the current Unix time in seconds for &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;.&lt;br /&gt;
# Build the signed text from the timestamp, the nonce, the method, the path and query (in lower case), and the exact body you are going to send.&lt;br /&gt;
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.&lt;br /&gt;
# Send the request with the &amp;lt;code&amp;gt;x-pos-key&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
&lt;br /&gt;
Barion checks that:&lt;br /&gt;
* the timestamp is within 5 minutes of the server time, in either direction,&lt;br /&gt;
* the nonce has not been used by the shop before (so a captured request cannot be replayed),&lt;br /&gt;
* the signature matches the request signed with the active key.&lt;br /&gt;
&lt;br /&gt;
== Verifying Barion&#039;s messages ==&lt;br /&gt;
&lt;br /&gt;
For a response to your request, and for a payment IPN message:&lt;br /&gt;
# Read the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
# Build the signed text: for a response with the response&#039;s status code and body, for an IPN with &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt;, the path and query of your callback URL as it was called (including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; query parameter), in lower case, and the request body.&lt;br /&gt;
# Compute the HMAC-SHA512 with your active key and compare it with &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt;. Use a constant-time comparison.&lt;br /&gt;
# Reject the message if the signature does not match. We also recommend rejecting it if the timestamp is more than a few minutes off your server time, and, for an IPN, if you have already processed its nonce.&amp;lt;br /&amp;gt;&lt;br /&gt;
== Example ==&lt;br /&gt;
&lt;br /&gt;
Signing a request in C#:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
using System;&lt;br /&gt;
using System.Security.Cryptography;&lt;br /&gt;
using System.Text;&lt;br /&gt;
&lt;br /&gt;
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)&lt;br /&gt;
{&lt;br /&gt;
    // The path and query are signed in lower case; the body is used as it is.&lt;br /&gt;
    string text = string.Join(&amp;quot;\n&amp;quot;, timestamp, nonce, method.ToUpperInvariant(), pathAndQuery.ToLowerInvariant(), body ?? &amp;quot;&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))&lt;br /&gt;
    {&lt;br /&gt;
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();&lt;br /&gt;
string nonce = Guid.NewGuid().ToString();&lt;br /&gt;
string body = &amp;quot;{\&amp;quot;PaymentRequestId\&amp;quot;:\&amp;quot;...\&amp;quot;}&amp;quot;;&lt;br /&gt;
string signature = Sign(hmacKey, timestamp, nonce, &amp;quot;POST&amp;quot;, &amp;quot;/v2/Payment/Start&amp;quot;, body);&lt;br /&gt;
&lt;br /&gt;
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Test vectors ==&lt;br /&gt;
&lt;br /&gt;
Use these known values to check your implementation. The bodies are made up and are not real requests or responses.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;HMAC key&#039;&#039;&#039; (base64): &amp;lt;code&amp;gt;AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
In the signed texts below, &amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt; stands for a single line feed character (LF, no carriage return). It is shown at the end of the line where it belongs; the last line has none, unless the body is empty.&lt;br /&gt;
&lt;br /&gt;
=== 1. A request with a JSON body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL:           https://api.barion.com/v2/Payment/Start&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (note that the path is in lower case, and the body is used as it is):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
POST\n&lt;br /&gt;
/v2/payment/start\n&lt;br /&gt;
{&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (118 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a504f53540a2f76322f7061796d656e742f73746172740a7b225061796d656e74526571756573744964223a226f726465722d31303031222c22546f74616c223a31302e35307d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
AMm7BeXNw0JAs8pxAhemnOQzhlWDz+o/nB85yKPim0DYSCdgpswBQFyQlhFrDwb/MrPFWlcwgDGa+DFGsNJvuQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 2. A GET request without a body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        GET&lt;br /&gt;
URL:           https://api.barion.com/v4/Payment/GetPaymentState?PaymentId=3F2B6C1E-8D4A-4B9E-9A51-0C7D2E6F1A84&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f&lt;br /&gt;
Body:          (none)&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. The path and the whole query string are in lower case, including the value of &amp;lt;code&amp;gt;PaymentId&amp;lt;/code&amp;gt;. The text ends with the line feed after the query string, because the body is empty:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f\n&lt;br /&gt;
GET\n&lt;br /&gt;
/v4/payment/getpaymentstate?paymentid=3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (127 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a39643661316630652d326237632d346333352d386531392d3561346233633264316530660a4745540a2f76342f7061796d656e742f6765747061796d656e7473746174653f7061796d656e7469643d33663262366331652d386434612d346239652d396135312d3063376432653666316138340a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
z8YFYV7YKs4OY4eVfd0BSc1LJMkbmBQRFuNXFO+KiAujB7eR1oHwicRTepgVSDqzHoHow/SDoKTdX2IpNMvB8A==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 3. A response ===&lt;br /&gt;
&lt;br /&gt;
This is Barion&#039;s answer to the request in example 1. It carries the &amp;lt;b&amp;gt;nonce of the request&amp;lt;/b&amp;gt; in its &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and it has its own timestamp.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
HTTP status:   200&lt;br /&gt;
x-timestamp:   1760968801&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. There is no method and no path in a response, only the status code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968801\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
200\n&lt;br /&gt;
{&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (120 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830310a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a3230300a7b225061796d656e744964223a223366326236633165386434613462396539613531306337643265366631613834222c22537461747573223a225072657061726564227d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
7C8tktY2Bs91dyw7L/fLKwDQCyriGiVOEvbrurn79sLkT2Q93KDVw7c/LEz4VWIqhZOpzLQbs7a6UCo5BZALyQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 5. A payment IPN message ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL called:    https://shop.example/hu/DemoClub/Callback?paymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
x-timestamp:   1760968802&lt;br /&gt;
x-nonce:       7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d&lt;br /&gt;
Body:          PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (the path is in lower case, the scheme and the host are not part of it):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968802\n&lt;br /&gt;
7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d\n&lt;br /&gt;
POST\n&lt;br /&gt;
/hu/democlub/callback?paymentid=4d924e8da6cbf11199f4001dd8b71d1a\n&lt;br /&gt;
PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (160 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830320a37623165346432612d366333662d346138622d396435302d3165326633613462356336640a504f53540a2f68752f64656d6f636c75622f63616c6c6261636b3f7061796d656e7469643d34643932346538646136636266313131393966343030316464386237316431610a5061796d656e7449643d3464393234653864613663626631313139396634303031646438623731643161&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
nwEdCk0K1LeDxLqF+4QnUgtmvl0BQPGqLUl+YawMMoJhcNXnJM9xT8JlmsNyWPwWktbJo2oy+yzx6cUMqUrRiA==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Rotating the key ==&lt;br /&gt;
&lt;br /&gt;
# Generate a second key on the security page, but do not set it as Active. The current key keeps working.&lt;br /&gt;
# Prepare your server to use the newly generated key. It should be able to accept messages signed with the new key, but still use the old key for signing requests.&lt;br /&gt;
# Mark the new key as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the security page. From that moment Barion signs with the new key and checks your requests against it. For the 24 hour change period Barion still accepts requests signed with the old key.&lt;br /&gt;
# Switch your server to use the new key for signing requests within this change period.&lt;br /&gt;
# Once your server uses the new key, we recommend that you &amp;lt;b&amp;gt;delete the old key&amp;lt;/b&amp;gt; on the security page right away. Barion then rejects requests signed with it immediately, instead of accepting them until the change period ends. Deleting it also frees a place for the next key.&lt;br /&gt;
&lt;br /&gt;
== Turning signing off ==&lt;br /&gt;
&lt;br /&gt;
Untick &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the active key. Barion stops signing its messages right away and no longer checks the signature of your requests. If your server rejects unsigned messages, it will reject Barion&#039;s IPN messages and responses too.&lt;br /&gt;
&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status &amp;lt;code&amp;gt;401&amp;lt;/code&amp;gt; and one of these errors:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Error code !! Meaning&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;MissingSignature&amp;lt;/code&amp;gt; || One or more of the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers is missing.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidNonce&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; is not a GUID.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidTimestamp&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt; is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidSignature&amp;lt;/code&amp;gt; || The signature does not match the request signed with the shop&#039;s active HMAC key.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;ReplayedRequest&amp;lt;/code&amp;gt; || A request with this &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; has already been received.&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4956</id>
		<title>Barion Shop Authentication</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4956"/>
		<updated>2026-10-21T08:09:49Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= What is shop authentication? =&lt;br /&gt;
&lt;br /&gt;
The API endpoints related to handling a shop&#039;s payment flow are accessible using the shop&#039;s own unique API key, known as &amp;lt;i&amp;gt;POS key&amp;lt;/i&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
For a full list of such endpoints see [[List_of_API_endpoints|List of Barion API endpoints]].&lt;br /&gt;
&lt;br /&gt;
Optionally, the shop can also use an &amp;lt;i&amp;gt;HMAC key&amp;lt;/i&amp;gt; to sign its API requests and to verify the messages Barion sends to it. See [[#Message signature (HMAC)|Message signature (HMAC)]].&lt;br /&gt;
&lt;br /&gt;
= Using POS keys =&lt;br /&gt;
&lt;br /&gt;
To use an endpoint which requires shop-level authentication, pass your Barion shop&#039;s POS key as the &#039;&#039;&#039;x-pos-key&#039;&#039;&#039; header parameter.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=&amp;lt;tt&amp;gt;GET&amp;lt;/tt&amp;gt; API endpoints below v4 also accept the &amp;lt;code&amp;gt;PosKey&amp;lt;/code&amp;gt; property as a query parameter.|color=#038Ed3}}&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
An invalid key generates an &amp;lt;code&amp;gt;AuthenticationFailed&amp;lt;/code&amp;gt; error.&lt;br /&gt;
&lt;br /&gt;
= Managing POS keys =&lt;br /&gt;
&lt;br /&gt;
A POS key is automatically generated for your shop when you create it, and cannot be changed later. To obtain it, either&lt;br /&gt;
* get the key from the confirmation e-mail that was sent to you when you opened the shop, or&lt;br /&gt;
* go to the shop&#039;s detail page on the [https://secure.barion.com Barion secure site] and use the &amp;lt;i&amp;gt;Secret key&amp;lt;/i&amp;gt; value (Shops -&amp;gt; Actions -&amp;gt; Details)&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=The test and live environment are completely separate environments, you need to create different shops. Make sure that you use the POSkey and not the public key:&lt;br /&gt;
&lt;br /&gt;
[[File:Poskey.jpg]] |color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
= Message signature (HMAC) =&lt;br /&gt;
&lt;br /&gt;
A shop can have an HMAC key in addition to its POS key. While the shop has an &amp;lt;b&amp;gt;active&amp;lt;/b&amp;gt; HMAC key:&lt;br /&gt;
* every API request authenticated with the shop&#039;s POS key &amp;lt;b&amp;gt;must be signed&amp;lt;/b&amp;gt; with the HMAC key, otherwise Barion rejects it,&lt;br /&gt;
* Barion signs its responses to these requests, and&lt;br /&gt;
* Barion signs the payment IPN (callback) messages it sends to the shop.&lt;br /&gt;
&lt;br /&gt;
This lets your server verify that a message really comes from Barion and was not changed on the way, and lets Barion verify that a request really comes from your shop.&lt;br /&gt;
&lt;br /&gt;
The signature is an HMAC-SHA512 computed with the shop&#039;s HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=From the moment you activate a key, Barion signs its responses and IPN messages with it. For your requests there is a &amp;lt;b&amp;gt;24 hour change period&amp;lt;/b&amp;gt;: during it Barion still accepts unsigned requests, and requests signed with the previous key if there was one. After it, every unsigned or wrongly signed request of the shop is rejected, payment start included. Signature headers are ignored while the shop has no active key, so start signing your requests &amp;lt;b&amp;gt;before&amp;lt;/b&amp;gt; you activate the key.|color=#D73E48}}&lt;br /&gt;
&lt;br /&gt;
== Managing HMAC keys ==&lt;br /&gt;
&lt;br /&gt;
HMAC keys are managed on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Settings -&amp;gt; Security -&amp;gt; Manage).&lt;br /&gt;
&lt;br /&gt;
* A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.&lt;br /&gt;
* A new key is created &amp;lt;b&amp;gt;inactive&amp;lt;/b&amp;gt;. Mark it as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; when your server is ready.&lt;br /&gt;
* At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.&lt;br /&gt;
* The active key cannot be deleted. Deactivate it, or activate the other key, first.&lt;br /&gt;
* The key is shown and copied as a base64 string. &amp;lt;b&amp;gt;Decode it from base64&amp;lt;/b&amp;gt; and use the resulting 64 bytes as the HMAC key.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=Keep the HMAC key on your server only, like the POS key. If you think a key is compromised, generate a new one, switch to it and delete the old one.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Signature headers ==&lt;br /&gt;
&lt;br /&gt;
Every signed request and response carries these three headers:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Header !! Content&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-timestamp&#039;&#039;&#039; || The time of signing as a Unix timestamp in seconds (UTC), e.g. &amp;lt;code&amp;gt;1760968800&amp;lt;/code&amp;gt;.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-nonce&#039;&#039;&#039; || A GUID, e.g. &amp;lt;code&amp;gt;3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&amp;lt;/code&amp;gt;. In a request it must be new for every request. In a response it is the nonce of the request being answered.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-signature-sha512&#039;&#039;&#039; || The HMAC-SHA512 of the signed text (see below), base64-encoded.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== The signed text ==&lt;br /&gt;
&lt;br /&gt;
The signature is computed over a text made of the following parts, joined with a single line feed character (&amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt;, LF, no carriage return). The text is UTF-8 encoded before signing.&lt;br /&gt;
&lt;br /&gt;
=== Requests (your API requests and Barion&#039;s IPN) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;HTTP method&#039;&#039;&#039;: in upper case, e.g. &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;path and query&#039;&#039;&#039;: the path and the query string of the URL as it appears on the request line, &#039;&#039;&#039;in lower case&#039;&#039;&#039;, e.g. &amp;lt;code&amp;gt;/v2/payment/start&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;/v4/payment/getpaymentstate?paymentid=...&amp;lt;/code&amp;gt;. The scheme, the host and the port are not part of it.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact request body, byte for byte as it is sent, and &#039;&#039;&#039;not&#039;&#039;&#039; changed to lower case. The body must be UTF-8 (a leading byte order mark is ignored). For a request without a body (e.g. &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;) it is an empty string, so the text ends with the line feed after the path.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=The path and the query string are signed in &amp;lt;b&amp;gt;lower case&amp;lt;/b&amp;gt;, because some proxies change the case of the URL on the way. Lower-case the whole path and query string (including the hex digits of percent-encoding, &amp;lt;code&amp;gt;%C3&amp;lt;/code&amp;gt; becomes &amp;lt;code&amp;gt;%c3&amp;lt;/code&amp;gt;) before signing and verifying, with an invariant, culture-independent lower-casing. Only the URL is lower-cased: the body is always used exactly as it is sent. This also means that a change in the case of the URL is not detected by the signature.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
=== Responses (Barion&#039;s answers to your signed requests) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;x-nonce&#039;&#039;&#039;: the nonce of &amp;lt;b&amp;gt;your request&amp;lt;/b&amp;gt; that the response answers. It is echoed back in the response&#039;s &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and binds the response to your request.&lt;br /&gt;
* &#039;&#039;&#039;HTTP status code&#039;&#039;&#039;: as a number, e.g. &amp;lt;code&amp;gt;200&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact response body as received.&lt;br /&gt;
&lt;br /&gt;
Responses are signed only when the request was signed correctly.&lt;br /&gt;
&lt;br /&gt;
== Signing your API requests ==&lt;br /&gt;
&lt;br /&gt;
# Generate a new GUID for &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and take the current Unix time in seconds for &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;.&lt;br /&gt;
# Build the signed text from the timestamp, the nonce, the method, the path and query (in lower case), and the exact body you are going to send.&lt;br /&gt;
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.&lt;br /&gt;
# Send the request with the &amp;lt;code&amp;gt;x-pos-key&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
&lt;br /&gt;
Barion checks that:&lt;br /&gt;
* the timestamp is within 5 minutes of the server time, in either direction,&lt;br /&gt;
* the nonce has not been used by the shop before (so a captured request cannot be replayed),&lt;br /&gt;
* the signature matches the request signed with the active key.&lt;br /&gt;
&lt;br /&gt;
== Verifying Barion&#039;s messages ==&lt;br /&gt;
&lt;br /&gt;
For a response to your request, and for a payment IPN message:&lt;br /&gt;
# Read the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
# Build the signed text: for a response with the response&#039;s status code and body, for an IPN with &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt;, the path and query of your callback URL as it was called (including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; query parameter), in lower case, and the request body.&lt;br /&gt;
# Compute the HMAC-SHA512 with your active key and compare it with &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt;. Use a constant-time comparison.&lt;br /&gt;
# Reject the message if the signature does not match. We also recommend rejecting it if the timestamp is more than a few minutes off your server time, and, for an IPN, if you have already processed its nonce.&amp;lt;br /&amp;gt;&lt;br /&gt;
== Example ==&lt;br /&gt;
&lt;br /&gt;
Signing a request in C#:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
using System;&lt;br /&gt;
using System.Security.Cryptography;&lt;br /&gt;
using System.Text;&lt;br /&gt;
&lt;br /&gt;
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)&lt;br /&gt;
{&lt;br /&gt;
    // The path and query are signed in lower case; the body is used as it is.&lt;br /&gt;
    string text = string.Join(&amp;quot;\n&amp;quot;, timestamp, nonce, method.ToUpperInvariant(), pathAndQuery.ToLowerInvariant(), body ?? &amp;quot;&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))&lt;br /&gt;
    {&lt;br /&gt;
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();&lt;br /&gt;
string nonce = Guid.NewGuid().ToString();&lt;br /&gt;
string body = &amp;quot;{\&amp;quot;PaymentRequestId\&amp;quot;:\&amp;quot;...\&amp;quot;}&amp;quot;;&lt;br /&gt;
string signature = Sign(hmacKey, timestamp, nonce, &amp;quot;POST&amp;quot;, &amp;quot;/v2/Payment/Start&amp;quot;, body);&lt;br /&gt;
&lt;br /&gt;
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Test vectors ==&lt;br /&gt;
&lt;br /&gt;
Use these known values to check your implementation. The bodies are made up and are not real requests or responses. Every signature below was computed with Barion&#039;s own code and cross-checked with &amp;lt;code&amp;gt;openssl&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=This key is only for these examples. Never use it for a real shop.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;HMAC key&#039;&#039;&#039; (base64, to be decoded before use): &amp;lt;code&amp;gt;AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
It decodes to the 64 bytes &amp;lt;code&amp;gt;0x00, 0x01, 0x02, ... 0x3f&amp;lt;/code&amp;gt;, which is &amp;lt;code&amp;gt;000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f&amp;lt;/code&amp;gt; in hex.&lt;br /&gt;
&lt;br /&gt;
In the signed texts below, &amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt; stands for a single line feed character (LF, no carriage return). It is shown at the end of the line where it belongs; the last line has none, unless the body is empty.&lt;br /&gt;
&lt;br /&gt;
For every example the exact bytes that are signed are given too, in hex and in base64. The signature is the HMAC-SHA512 of these bytes with the decoded key. If your signature differs, compare your bytes with these first: an LF is &amp;lt;code&amp;gt;0a&amp;lt;/code&amp;gt; (a CR LF would be &amp;lt;code&amp;gt;0d0a&amp;lt;/code&amp;gt;), and non-ASCII characters are UTF-8 encoded.&lt;br /&gt;
&lt;br /&gt;
=== 1. A request with a JSON body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL:           https://api.barion.com/v2/Payment/Start&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (note that the path is in lower case, and the body is used as it is):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
POST\n&lt;br /&gt;
/v2/payment/start\n&lt;br /&gt;
{&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (118 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a504f53540a2f76322f7061796d656e742f73746172740a7b225061796d656e74526571756573744964223a226f726465722d31303031222c22546f74616c223a31302e35307d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and in base64:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
MTc2MDk2ODgwMAozZjJiNmMxZS04ZDRhLTRiOWUtOWE1MS0wYzdkMmU2ZjFhODQKUE9TVAovdjIvcGF5bWVudC9zdGFydAp7IlBheW1lbnRSZXF1ZXN0SWQiOiJvcmRlci0xMDAxIiwiVG90YWwiOjEwLjUwfQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
AMm7BeXNw0JAs8pxAhemnOQzhlWDz+o/nB85yKPim0DYSCdgpswBQFyQlhFrDwb/MrPFWlcwgDGa+DFGsNJvuQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 2. A GET request without a body ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        GET&lt;br /&gt;
URL:           https://api.barion.com/v4/Payment/GetPaymentState?PaymentId=3F2B6C1E-8D4A-4B9E-9A51-0C7D2E6F1A84&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f&lt;br /&gt;
Body:          (none)&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. The path and the whole query string are in lower case, including the value of &amp;lt;code&amp;gt;PaymentId&amp;lt;/code&amp;gt;. The text ends with the line feed after the query string, because the body is empty:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f\n&lt;br /&gt;
GET\n&lt;br /&gt;
/v4/payment/getpaymentstate?paymentid=3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (127 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a39643661316630652d326237632d346333352d386531392d3561346233633264316530660a4745540a2f76342f7061796d656e742f6765747061796d656e7473746174653f7061796d656e7469643d33663262366331652d386434612d346239652d396135312d3063376432653666316138340a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and in base64:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
MTc2MDk2ODgwMAo5ZDZhMWYwZS0yYjdjLTRjMzUtOGUxOS01YTRiM2MyZDFlMGYKR0VUCi92NC9wYXltZW50L2dldHBheW1lbnRzdGF0ZT9wYXltZW50aWQ9M2YyYjZjMWUtOGQ0YS00YjllLTlhNTEtMGM3ZDJlNmYxYTg0Cg==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
z8YFYV7YKs4OY4eVfd0BSc1LJMkbmBQRFuNXFO+KiAujB7eR1oHwicRTepgVSDqzHoHow/SDoKTdX2IpNMvB8A==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 3. A request with a body that is not ASCII ===&lt;br /&gt;
&lt;br /&gt;
The body contains the characters &amp;lt;code&amp;gt;é&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;ő&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;€&amp;lt;/code&amp;gt;. It is signed as UTF-8, that is &amp;lt;code&amp;gt;c3 a9&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;c5 91&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;e2 82 ac&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL:           https://api.barion.com/v2/Payment/Refund&lt;br /&gt;
x-timestamp:   1760968800&lt;br /&gt;
x-nonce:       c0ffee00-1234-4abc-8def-0123456789ab&lt;br /&gt;
Body:          {&amp;quot;Comment&amp;quot;:&amp;quot;Pléhő €&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968800\n&lt;br /&gt;
c0ffee00-1234-4abc-8def-0123456789ab\n&lt;br /&gt;
POST\n&lt;br /&gt;
/v2/payment/refund\n&lt;br /&gt;
{&amp;quot;Comment&amp;quot;:&amp;quot;Pléhő €&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (97 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830300a63306666656530302d313233342d346162632d386465662d3031323334353637383961620a504f53540a2f76322f7061796d656e742f726566756e640a7b22436f6d6d656e74223a22506cc3a968c59120e282ac227d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and in base64:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
MTc2MDk2ODgwMApjMGZmZWUwMC0xMjM0LTRhYmMtOGRlZi0wMTIzNDU2Nzg5YWIKUE9TVAovdjIvcGF5bWVudC9yZWZ1bmQKeyJDb21tZW50IjoiUGzDqWjFkSDigqwifQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Hr/GW0mx6tAeDK32aPGAXoM2nk0IluJP+OPmxu3/PVWspiFWDlyAKTfeHn1Qd67KKHxNqa3gORiCvlYGbbnvUA==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 4. A response ===&lt;br /&gt;
&lt;br /&gt;
This is Barion&#039;s answer to the request in example 1. It carries the &amp;lt;b&amp;gt;nonce of the request&amp;lt;/b&amp;gt; in its &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and it has its own timestamp.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
HTTP status:   200&lt;br /&gt;
x-timestamp:   1760968801&lt;br /&gt;
x-nonce:       3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&lt;br /&gt;
Body:          {&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text. There is no method and no path in a response, only the status code:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968801\n&lt;br /&gt;
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n&lt;br /&gt;
200\n&lt;br /&gt;
{&amp;quot;PaymentId&amp;quot;:&amp;quot;3f2b6c1e8d4a4b9e9a510c7d2e6f1a84&amp;quot;,&amp;quot;Status&amp;quot;:&amp;quot;Prepared&amp;quot;}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (120 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830310a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a3230300a7b225061796d656e744964223a223366326236633165386434613462396539613531306337643265366631613834222c22537461747573223a225072657061726564227d&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and in base64:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
MTc2MDk2ODgwMQozZjJiNmMxZS04ZDRhLTRiOWUtOWE1MS0wYzdkMmU2ZjFhODQKMjAwCnsiUGF5bWVudElkIjoiM2YyYjZjMWU4ZDRhNGI5ZTlhNTEwYzdkMmU2ZjFhODQiLCJTdGF0dXMiOiJQcmVwYXJlZCJ9&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
7C8tktY2Bs91dyw7L/fLKwDQCyriGiVOEvbrurn79sLkT2Q93KDVw7c/LEz4VWIqhZOpzLQbs7a6UCo5BZALyQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== 5. A payment IPN message ===&lt;br /&gt;
&lt;br /&gt;
Barion calls your callback URL. Sign (or verify) the path and query of the URL &amp;lt;b&amp;gt;as it was called&amp;lt;/b&amp;gt;, including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; parameter, and the request body.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
Method:        POST&lt;br /&gt;
URL called:    https://shop.example/hu/DemoClub/Callback?paymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
x-timestamp:   1760968802&lt;br /&gt;
x-nonce:       7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d&lt;br /&gt;
Body:          PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed text (the path is in lower case, the scheme and the host are not part of it):&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
1760968802\n&lt;br /&gt;
7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d\n&lt;br /&gt;
POST\n&lt;br /&gt;
/hu/democlub/callback?paymentid=4d924e8da6cbf11199f4001dd8b71d1a\n&lt;br /&gt;
PaymentId=4d924e8da6cbf11199f4001dd8b71d1a&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Signed bytes: the UTF-8 encoding of the text above (160 bytes), in hex:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
313736303936383830320a37623165346432612d366333662d346138622d396435302d3165326633613462356336640a504f53540a2f68752f64656d6f636c75622f63616c6c6261636b3f7061796d656e7469643d34643932346538646136636266313131393966343030316464386237316431610a5061796d656e7449643d3464393234653864613663626631313139396634303031646438623731643161&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
and in base64:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
MTc2MDk2ODgwMgo3YjFlNGQyYS02YzNmLTRhOGItOWQ1MC0xZTJmM2E0YjVjNmQKUE9TVAovaHUvZGVtb2NsdWIvY2FsbGJhY2s/cGF5bWVudGlkPTRkOTI0ZThkYTZjYmYxMTE5OWY0MDAxZGQ4YjcxZDFhClBheW1lbnRJZD00ZDkyNGU4ZGE2Y2JmMTExOTlmNDAwMWRkOGI3MWQxYQ==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
x-signature-sha512:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
nwEdCk0K1LeDxLqF+4QnUgtmvl0BQPGqLUl+YawMMoJhcNXnJM9xT8JlmsNyWPwWktbJo2oy+yzx6cUMqUrRiA==&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
=== Checking a value from the command line ===&lt;br /&gt;
&lt;br /&gt;
For example, example 1 with &amp;lt;code&amp;gt;openssl&amp;lt;/code&amp;gt;:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
printf &#039;%s\n%s\nPOST\n%s\n%s&#039; 1760968800 3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84 /v2/payment/start &#039;{&amp;quot;PaymentRequestId&amp;quot;:&amp;quot;order-1001&amp;quot;,&amp;quot;Total&amp;quot;:10.50}&#039; \&lt;br /&gt;
  | openssl dgst -sha512 -mac HMAC -macopt hexkey:000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f -binary \&lt;br /&gt;
  | base64 -w0&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Rotating the key ==&lt;br /&gt;
&lt;br /&gt;
# Generate a second key on the security page, but do not set it as Active. The current key keeps working.&lt;br /&gt;
# Prepare your server to use the newly generated key. It should be able to accept messages signed with the new key, but still use the old key for signing requests.&lt;br /&gt;
# Mark the new key as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the security page. From that moment Barion signs with the new key and checks your requests against it. For the 24 hour change period Barion still accepts requests signed with the old key.&lt;br /&gt;
# Switch your server to use the new key for signing requests within this change period.&lt;br /&gt;
# Once your server uses the new key, we recommend that you &amp;lt;b&amp;gt;delete the old key&amp;lt;/b&amp;gt; on the security page right away. Barion then rejects requests signed with it immediately, instead of accepting them until the change period ends. Deleting it also frees a place for the next key.&lt;br /&gt;
&lt;br /&gt;
== Turning signing off ==&lt;br /&gt;
&lt;br /&gt;
Untick &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the active key. Barion stops signing its messages right away and no longer checks the signature of your requests. If your server rejects unsigned messages, it will reject Barion&#039;s IPN messages and responses too.&lt;br /&gt;
&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status &amp;lt;code&amp;gt;401&amp;lt;/code&amp;gt; and one of these errors:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Error code !! Meaning&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;MissingSignature&amp;lt;/code&amp;gt; || One or more of the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers is missing.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidNonce&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; is not a GUID.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidTimestamp&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt; is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidSignature&amp;lt;/code&amp;gt; || The signature does not match the request signed with the shop&#039;s active HMAC key.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;ReplayedRequest&amp;lt;/code&amp;gt; || A request with this &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; has already been received.&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4955</id>
		<title>Barion Shop Authentication</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4955"/>
		<updated>2026-10-21T07:20:32Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= What is shop authentication? =&lt;br /&gt;
&lt;br /&gt;
The API endpoints related to handling a shop&#039;s payment flow are accessible using the shop&#039;s own unique API key, known as &amp;lt;i&amp;gt;POS key&amp;lt;/i&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
For a full list of such endpoints see [[List_of_API_endpoints|List of Barion API endpoints]].&lt;br /&gt;
&lt;br /&gt;
Optionally, the shop can also use an &amp;lt;i&amp;gt;HMAC key&amp;lt;/i&amp;gt; to sign its API requests and to verify the messages Barion sends to it. See [[#Message signature (HMAC)|Message signature (HMAC)]].&lt;br /&gt;
&lt;br /&gt;
= Using POS keys =&lt;br /&gt;
&lt;br /&gt;
To use an endpoint which requires shop-level authentication, pass your Barion shop&#039;s POS key as the &#039;&#039;&#039;x-pos-key&#039;&#039;&#039; header parameter.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=&amp;lt;tt&amp;gt;GET&amp;lt;/tt&amp;gt; API endpoints below v4 also accept the &amp;lt;code&amp;gt;PosKey&amp;lt;/code&amp;gt; property as a query parameter.|color=#038Ed3}}&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
An invalid key generates an &amp;lt;code&amp;gt;AuthenticationFailed&amp;lt;/code&amp;gt; error.&lt;br /&gt;
&lt;br /&gt;
= Managing POS keys =&lt;br /&gt;
&lt;br /&gt;
A POS key is automatically generated for your shop when you create it, and cannot be changed later. To obtain it, either&lt;br /&gt;
* get the key from the confirmation e-mail that was sent to you when you opened the shop, or&lt;br /&gt;
* go to the shop&#039;s detail page on the [https://secure.barion.com Barion secure site] and use the &amp;lt;i&amp;gt;Secret key&amp;lt;/i&amp;gt; value (Shops -&amp;gt; Actions -&amp;gt; Details)&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=The test and live environment are completely separate environments, you need to create different shops. Make sure that you use the POSkey and not the public key:&lt;br /&gt;
&lt;br /&gt;
[[File:Poskey.jpg]] |color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
= Message signature (HMAC) =&lt;br /&gt;
&lt;br /&gt;
A shop can have an HMAC key in addition to its POS key. While the shop has an &amp;lt;b&amp;gt;active&amp;lt;/b&amp;gt; HMAC key:&lt;br /&gt;
* every API request authenticated with the shop&#039;s POS key &amp;lt;b&amp;gt;must be signed&amp;lt;/b&amp;gt; with the HMAC key, otherwise Barion rejects it,&lt;br /&gt;
* Barion signs its responses to these requests, and&lt;br /&gt;
* Barion signs the payment IPN (callback) messages it sends to the shop.&lt;br /&gt;
&lt;br /&gt;
This lets your server verify that a message really comes from Barion and was not changed on the way, and lets Barion verify that a request really comes from your shop.&lt;br /&gt;
&lt;br /&gt;
The signature is an HMAC-SHA512 computed with the shop&#039;s HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Activating a key takes effect &amp;lt;b&amp;gt;immediately&amp;lt;/b&amp;gt;: from that moment, every unsigned or wrongly signed request of the shop is rejected, payment start included. Signature headers are ignored while the shop has no active key, so start signing your requests &amp;lt;b&amp;gt;before&amp;lt;/b&amp;gt; you activate the key.|color=#D73E48}}&lt;br /&gt;
&lt;br /&gt;
== Managing HMAC keys ==&lt;br /&gt;
&lt;br /&gt;
HMAC keys are managed on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Settings -&amp;gt; Security -&amp;gt; Manage).&lt;br /&gt;
&lt;br /&gt;
* A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.&lt;br /&gt;
* A new key is created &amp;lt;b&amp;gt;inactive&amp;lt;/b&amp;gt;. Mark it as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; when your server is ready.&lt;br /&gt;
* At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.&lt;br /&gt;
* The active key cannot be deleted. Deactivate it, or activate the other key, first.&lt;br /&gt;
* The key is shown and copied as a base64 string. &amp;lt;b&amp;gt;Decode it from base64&amp;lt;/b&amp;gt; and use the resulting 64 bytes as the HMAC key.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=Keep the HMAC key on your server only, like the POS key. If you think a key is compromised, generate a new one, switch to it and delete the old one.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Signature headers ==&lt;br /&gt;
&lt;br /&gt;
Every signed request and response carries these three headers:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Header !! Content&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-timestamp&#039;&#039;&#039; || The time of signing as a Unix timestamp in seconds (UTC), e.g. &amp;lt;code&amp;gt;1760968800&amp;lt;/code&amp;gt;.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-nonce&#039;&#039;&#039; || A GUID, e.g. &amp;lt;code&amp;gt;3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&amp;lt;/code&amp;gt;. In a request it must be new for every request. In a response it is the nonce of the request being answered.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-signature-sha512&#039;&#039;&#039; || The HMAC-SHA512 of the signed text (see below), base64-encoded.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== The signed text ==&lt;br /&gt;
&lt;br /&gt;
The signature is computed over a text made of the following parts, joined with a single line feed character (&amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt;, LF, no carriage return). The text is UTF-8 encoded before signing.&lt;br /&gt;
&lt;br /&gt;
=== Requests (your API requests and Barion&#039;s IPN) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;HTTP method&#039;&#039;&#039;: in upper case, e.g. &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;path and query&#039;&#039;&#039;: the path and the query string of the URL as it appears on the request line, e.g. &amp;lt;code&amp;gt;/v2/Payment/Start&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;/v4/Payment/GetPaymentState?PaymentId=...&amp;lt;/code&amp;gt;. The scheme, the host and the port are not part of it.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact request body, byte for byte as it is sent. For a request without a body (e.g. &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;) it is an empty string, so the text ends with the line feed after the path.&lt;br /&gt;
&lt;br /&gt;
=== Responses (Barion&#039;s answers to your signed requests) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;x-nonce&#039;&#039;&#039;: the nonce of &amp;lt;b&amp;gt;your request&amp;lt;/b&amp;gt; that the response answers. It is echoed back in the response&#039;s &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and binds the response to your request.&lt;br /&gt;
* &#039;&#039;&#039;HTTP status code&#039;&#039;&#039;: as a number, e.g. &amp;lt;code&amp;gt;200&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact response body as received.&lt;br /&gt;
&lt;br /&gt;
Responses are signed only when the request was signed correctly.&lt;br /&gt;
&lt;br /&gt;
== Signing your API requests ==&lt;br /&gt;
&lt;br /&gt;
# Generate a new GUID for &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and take the current Unix time in seconds for &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;.&lt;br /&gt;
# Build the signed text from the timestamp, the nonce, the method, the path and query, and the exact body you are going to send.&lt;br /&gt;
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.&lt;br /&gt;
# Send the request with the &amp;lt;code&amp;gt;x-pos-key&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
&lt;br /&gt;
Barion checks that:&lt;br /&gt;
* the timestamp is within 5 minutes of the server time, in either direction,&lt;br /&gt;
* the nonce has not been used by the shop before (so a captured request cannot be replayed),&lt;br /&gt;
* the signature matches the request signed with the active key.&lt;br /&gt;
&lt;br /&gt;
== Verifying Barion&#039;s messages ==&lt;br /&gt;
&lt;br /&gt;
For a response to your request, and for a payment IPN message:&lt;br /&gt;
# Read the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
# Build the signed text: for a response with the response&#039;s status code and body, for an IPN with &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt;, the path and query of your callback URL as it was called (including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; query parameter) and the request body.&lt;br /&gt;
# Compute the HMAC-SHA512 with your active key and compare it with &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt;. Use a constant-time comparison.&lt;br /&gt;
# Reject the message if the signature does not match. We also recommend rejecting it if the timestamp is more than a few minutes off your server time, and, for an IPN, if you have already processed its nonce.&amp;lt;br /&amp;gt;&lt;br /&gt;
== Example ==&lt;br /&gt;
&lt;br /&gt;
Signing a request in C#:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
using System;&lt;br /&gt;
using System.Security.Cryptography;&lt;br /&gt;
using System.Text;&lt;br /&gt;
&lt;br /&gt;
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)&lt;br /&gt;
{&lt;br /&gt;
    string text = string.Join(&amp;quot;\n&amp;quot;, timestamp, nonce, method.ToUpperInvariant(), pathAndQuery, body ?? &amp;quot;&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))&lt;br /&gt;
    {&lt;br /&gt;
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();&lt;br /&gt;
string nonce = Guid.NewGuid().ToString();&lt;br /&gt;
string body = &amp;quot;{\&amp;quot;PaymentRequestId\&amp;quot;:\&amp;quot;...\&amp;quot;}&amp;quot;;&lt;br /&gt;
string signature = Sign(hmacKey, timestamp, nonce, &amp;quot;POST&amp;quot;, &amp;quot;/v2/Payment/Start&amp;quot;, body);&lt;br /&gt;
&lt;br /&gt;
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Rotating the key ==&lt;br /&gt;
&lt;br /&gt;
# Generate a second key on the security page, but do not set it as Active. The current key keeps working.&lt;br /&gt;
# Prepare your server to use the newly generated key. It should be able to accept messages signed with the new key, but still use the old key for signing requests.&lt;br /&gt;
# Mark the new key as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the security page. From that moment Barion signs with the new key and checks your requests against it. Barion will accept messages signed with the old key for 24 hours.&lt;br /&gt;
# Switch your server to use the new key for signing requests in this timeframe.&lt;br /&gt;
# Once your server no longer uses the old key, delete the old key on the security page, so Barion won&#039;t accept messages signed with it anymore.&lt;br /&gt;
&lt;br /&gt;
== Turning signing off ==&lt;br /&gt;
&lt;br /&gt;
Untick &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the active key. Barion stops signing its messages right away and no longer checks the signature of your requests. If your server rejects unsigned messages, it will reject Barion&#039;s IPN messages and responses too.&lt;br /&gt;
&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status &amp;lt;code&amp;gt;401&amp;lt;/code&amp;gt; and one of these errors:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Error code !! Meaning&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;MissingSignature&amp;lt;/code&amp;gt; || One or more of the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers is missing.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidNonce&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; is not a GUID.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidTimestamp&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt; is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidSignature&amp;lt;/code&amp;gt; || The signature does not match the request signed with the shop&#039;s active HMAC key.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;ReplayedRequest&amp;lt;/code&amp;gt; || A request with this &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; has already been received.&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4954</id>
		<title>Barion Shop Authentication</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4954"/>
		<updated>2026-10-20T14:56:14Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= What is shop authentication? =&lt;br /&gt;
&lt;br /&gt;
The API endpoints related to handling a shop&#039;s payment flow are accessible using the shop&#039;s own unique API key, known as &amp;lt;i&amp;gt;POS key&amp;lt;/i&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
For a full list of such endpoints see [[List_of_API_endpoints|List of Barion API endpoints]].&lt;br /&gt;
&lt;br /&gt;
Optionally, the shop can also use an &amp;lt;i&amp;gt;HMAC key&amp;lt;/i&amp;gt; to sign its API requests and to verify the messages Barion sends to it. See [[#Message signature (HMAC)|Message signature (HMAC)]].&lt;br /&gt;
&lt;br /&gt;
= Using POS keys =&lt;br /&gt;
&lt;br /&gt;
To use an endpoint which requires shop-level authentication, pass your Barion shop&#039;s POS key as the &#039;&#039;&#039;x-pos-key&#039;&#039;&#039; header parameter.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=&amp;lt;tt&amp;gt;GET&amp;lt;/tt&amp;gt; API endpoints below v4 also accept the &amp;lt;code&amp;gt;PosKey&amp;lt;/code&amp;gt; property as a query parameter.|color=#038Ed3}}&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
An invalid key generates an &amp;lt;code&amp;gt;AuthenticationFailed&amp;lt;/code&amp;gt; error.&lt;br /&gt;
&lt;br /&gt;
= Managing POS keys =&lt;br /&gt;
&lt;br /&gt;
A POS key is automatically generated for your shop when you create it, and cannot be changed later. To obtain it, either&lt;br /&gt;
* get the key from the confirmation e-mail that was sent to you when you opened the shop, or&lt;br /&gt;
* go to the shop&#039;s detail page on the [https://secure.barion.com Barion secure site] and use the &amp;lt;i&amp;gt;Secret key&amp;lt;/i&amp;gt; value (Shops -&amp;gt; Actions -&amp;gt; Details)&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=The test and live environment are completely separate environments, you need to create different shops. Make sure that you use the POSkey and not the public key:&lt;br /&gt;
&lt;br /&gt;
[[File:Poskey.jpg]] |color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
= Message signature (HMAC) =&lt;br /&gt;
&lt;br /&gt;
A shop can have an HMAC key in addition to its POS key. While the shop has an &amp;lt;b&amp;gt;active&amp;lt;/b&amp;gt; HMAC key:&lt;br /&gt;
* every API request authenticated with the shop&#039;s POS key &amp;lt;b&amp;gt;must be signed&amp;lt;/b&amp;gt; with the HMAC key, otherwise Barion rejects it,&lt;br /&gt;
* Barion signs its responses to these requests, and&lt;br /&gt;
* Barion signs the payment IPN (callback) messages it sends to the shop.&lt;br /&gt;
&lt;br /&gt;
This lets your server verify that a message really comes from Barion and was not changed on the way, and lets Barion verify that a request really comes from your shop.&lt;br /&gt;
&lt;br /&gt;
The signature is an HMAC-SHA512 computed with the shop&#039;s HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Activating a key takes effect &amp;lt;b&amp;gt;immediately&amp;lt;/b&amp;gt;: from that moment, every unsigned or wrongly signed request of the shop is rejected, payment start included. Signature headers are ignored while the shop has no active key, so start signing your requests &amp;lt;b&amp;gt;before&amp;lt;/b&amp;gt; you activate the key.|color=#D73E48}}&lt;br /&gt;
&lt;br /&gt;
== Managing HMAC keys ==&lt;br /&gt;
&lt;br /&gt;
HMAC keys are managed on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Settings -&amp;gt; Security -&amp;gt; Manage).&lt;br /&gt;
&lt;br /&gt;
* A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.&lt;br /&gt;
* A new key is created &amp;lt;b&amp;gt;inactive&amp;lt;/b&amp;gt;. Mark it as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; when your server is ready.&lt;br /&gt;
* At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.&lt;br /&gt;
* The active key cannot be deleted. Deactivate it, or activate the other key, first.&lt;br /&gt;
* The key is shown and copied as a base64 string. &amp;lt;b&amp;gt;Decode it from base64&amp;lt;/b&amp;gt; and use the resulting 64 bytes as the HMAC key.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=Keep the HMAC key on your server only, like the POS key. If you think a key is compromised, generate a new one, switch to it and delete the old one.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Signature headers ==&lt;br /&gt;
&lt;br /&gt;
Every signed request and response carries these three headers:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Header !! Content&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-timestamp&#039;&#039;&#039; || The time of signing as a Unix timestamp in seconds (UTC), e.g. &amp;lt;code&amp;gt;1760968800&amp;lt;/code&amp;gt;.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-nonce&#039;&#039;&#039; || A GUID, e.g. &amp;lt;code&amp;gt;3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&amp;lt;/code&amp;gt;. In a request it must be new for every request. In a response it is the nonce of the request being answered.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-signature-sha512&#039;&#039;&#039; || The HMAC-SHA512 of the signed text (see below), base64-encoded.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== The signed text ==&lt;br /&gt;
&lt;br /&gt;
The signature is computed over a text made of the following parts, joined with a single line feed character (&amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt;, LF, no carriage return). The text is UTF-8 encoded before signing.&lt;br /&gt;
&lt;br /&gt;
=== Requests (your API requests and Barion&#039;s IPN) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;HTTP method&#039;&#039;&#039;: in upper case, e.g. &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;path and query&#039;&#039;&#039;: the path and the query string of the URL as it appears on the request line, e.g. &amp;lt;code&amp;gt;/v2/Payment/Start&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;/v4/Payment/GetPaymentState?PaymentId=...&amp;lt;/code&amp;gt;. The scheme, the host and the port are not part of it.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact request body, byte for byte as it is sent. For a request without a body (e.g. &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;) it is an empty string, so the text ends with the line feed after the path.&lt;br /&gt;
&lt;br /&gt;
=== Responses (Barion&#039;s answers to your signed requests) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;x-nonce&#039;&#039;&#039;: the nonce of &amp;lt;b&amp;gt;your request&amp;lt;/b&amp;gt; that the response answers. It is echoed back in the response&#039;s &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and binds the response to your request.&lt;br /&gt;
* &#039;&#039;&#039;HTTP status code&#039;&#039;&#039;: as a number, e.g. &amp;lt;code&amp;gt;200&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact response body as received.&lt;br /&gt;
&lt;br /&gt;
Responses are signed only when the request was signed correctly.&lt;br /&gt;
&lt;br /&gt;
== Signing your API requests ==&lt;br /&gt;
&lt;br /&gt;
# Generate a new GUID for &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and take the current Unix time in seconds for &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;.&lt;br /&gt;
# Build the signed text from the timestamp, the nonce, the method, the path and query, and the exact body you are going to send.&lt;br /&gt;
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.&lt;br /&gt;
# Send the request with the &amp;lt;code&amp;gt;x-pos-key&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
&lt;br /&gt;
Barion checks that:&lt;br /&gt;
* the timestamp is within 5 minutes of the server time, in either direction,&lt;br /&gt;
* the nonce has not been used by the shop before (so a captured request cannot be replayed),&lt;br /&gt;
* the signature matches the request signed with the active key.&lt;br /&gt;
&lt;br /&gt;
== Verifying Barion&#039;s messages ==&lt;br /&gt;
&lt;br /&gt;
For a response to your request, and for a payment IPN message:&lt;br /&gt;
# Read the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
# Build the signed text: for a response with the response&#039;s status code and body, for an IPN with &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt;, the path and query of your callback URL as it was called (including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; query parameter) and the request body.&lt;br /&gt;
# Compute the HMAC-SHA512 with your active key and compare it with &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt;. Use a constant-time comparison.&lt;br /&gt;
# Reject the message if the signature does not match. We also recommend rejecting it if the timestamp is more than a few minutes off your server time, and, for an IPN, if you have already processed its nonce.&amp;lt;br /&amp;gt;&lt;br /&gt;
== Example ==&lt;br /&gt;
&lt;br /&gt;
Signing a request in C#:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
using System;&lt;br /&gt;
using System.Security.Cryptography;&lt;br /&gt;
using System.Text;&lt;br /&gt;
&lt;br /&gt;
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)&lt;br /&gt;
{&lt;br /&gt;
    string text = string.Join(&amp;quot;\n&amp;quot;, timestamp, nonce, method.ToUpperInvariant(), pathAndQuery, body ?? &amp;quot;&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))&lt;br /&gt;
    {&lt;br /&gt;
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();&lt;br /&gt;
string nonce = Guid.NewGuid().ToString();&lt;br /&gt;
string body = &amp;quot;{\&amp;quot;PaymentRequestId\&amp;quot;:\&amp;quot;...\&amp;quot;}&amp;quot;;&lt;br /&gt;
string signature = Sign(hmacKey, timestamp, nonce, &amp;quot;POST&amp;quot;, &amp;quot;/v2/Payment/Start&amp;quot;, body);&lt;br /&gt;
&lt;br /&gt;
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Rotating the key ==&lt;br /&gt;
&lt;br /&gt;
# Generate a second key on the security page, but do not set it as Active. The current key keeps working.&lt;br /&gt;
# Prepare your server to use the newly generated key. It should be able to accept messages signed with the new key, but still use the old key for signing requests.&lt;br /&gt;
# Mark the new key as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the security page. From that moment Barion signs with the new key and checks your requests against it. Barion will accept messages signed with the old key for 5 minutes.&lt;br /&gt;
# Switch your server to use the new key for signing requests in this timeframe.&lt;br /&gt;
# Once your server no longer uses the old key, delete the old key.&lt;br /&gt;
&lt;br /&gt;
== Turning signing off ==&lt;br /&gt;
&lt;br /&gt;
Untick &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the active key. Barion stops signing its messages right away and no longer checks the signature of your requests. If your server rejects unsigned messages, it will reject Barion&#039;s IPN messages and responses too.&lt;br /&gt;
&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status &amp;lt;code&amp;gt;401&amp;lt;/code&amp;gt; and one of these errors:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Error code !! Meaning&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;MissingSignature&amp;lt;/code&amp;gt; || One or more of the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers is missing.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidNonce&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; is not a GUID.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidTimestamp&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt; is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidSignature&amp;lt;/code&amp;gt; || The signature does not match the request signed with the shop&#039;s active HMAC key.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;ReplayedRequest&amp;lt;/code&amp;gt; || A request with this &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; has already been received.&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4953</id>
		<title>Barion Shop Authentication</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Barion_Shop_Authentication&amp;diff=4953"/>
		<updated>2026-10-20T14:45:57Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: &lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;= What is shop authentication? =&lt;br /&gt;
&lt;br /&gt;
The API endpoints related to handling a shop&#039;s payment flow are accessible using the shop&#039;s own unique API key, known as &amp;lt;i&amp;gt;POS key&amp;lt;/i&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
For a full list of such endpoints see [[List_of_API_endpoints|List of Barion API endpoints]].&lt;br /&gt;
&lt;br /&gt;
Optionally, the shop can also use an &amp;lt;i&amp;gt;HMAC key&amp;lt;/i&amp;gt; to sign its API requests and to verify the messages Barion sends to it. See [[#Message signature (HMAC)|Message signature (HMAC)]].&lt;br /&gt;
&lt;br /&gt;
= Using POS keys =&lt;br /&gt;
&lt;br /&gt;
To use an endpoint which requires shop-level authentication, pass your Barion shop&#039;s POS key as the &#039;&#039;&#039;x-pos-key&#039;&#039;&#039; header parameter.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=&amp;lt;tt&amp;gt;GET&amp;lt;/tt&amp;gt; API endpoints below v4 also accept the &amp;lt;code&amp;gt;PosKey&amp;lt;/code&amp;gt; property as a query parameter.|color=#038Ed3}}&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
An invalid key generates an &amp;lt;code&amp;gt;AuthenticationFailed&amp;lt;/code&amp;gt; error.&lt;br /&gt;
&lt;br /&gt;
= Managing POS keys =&lt;br /&gt;
&lt;br /&gt;
A POS key is automatically generated for your shop when you create it, and cannot be changed later. To obtain it, either&lt;br /&gt;
* get the key from the confirmation e-mail that was sent to you when you opened the shop, or&lt;br /&gt;
* go to the shop&#039;s detail page on the [https://secure.barion.com Barion secure site] and use the &amp;lt;i&amp;gt;Secret key&amp;lt;/i&amp;gt; value (Shops -&amp;gt; Actions -&amp;gt; Details)&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=The test and live environment are completely separate environments, you need to create different shops. Make sure that you use the POSkey and not the public key:&lt;br /&gt;
&lt;br /&gt;
[[File:Poskey.jpg]] |color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
= Message signature (HMAC) =&lt;br /&gt;
&lt;br /&gt;
A shop can have an HMAC key in addition to its POS key. While the shop has an &amp;lt;b&amp;gt;active&amp;lt;/b&amp;gt; HMAC key:&lt;br /&gt;
* every API request authenticated with the shop&#039;s POS key &amp;lt;b&amp;gt;must be signed&amp;lt;/b&amp;gt; with the HMAC key, otherwise Barion rejects it,&lt;br /&gt;
* Barion signs its responses to these requests, and&lt;br /&gt;
* Barion signs the payment IPN (callback) messages it sends to the shop.&lt;br /&gt;
&lt;br /&gt;
This lets your server verify that a message really comes from Barion and was not changed on the way, and lets Barion verify that a request really comes from your shop.&lt;br /&gt;
&lt;br /&gt;
The signature is an HMAC-SHA512 computed with the shop&#039;s HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=Activating a key takes effect &amp;lt;b&amp;gt;immediately&amp;lt;/b&amp;gt;: from that moment, every unsigned or wrongly signed request of the shop is rejected, payment start included. Signature headers are ignored while the shop has no active key, so start signing your requests &amp;lt;b&amp;gt;before&amp;lt;/b&amp;gt; you activate the key.|color=#D73E48}}&lt;br /&gt;
&lt;br /&gt;
== Managing HMAC keys ==&lt;br /&gt;
&lt;br /&gt;
HMAC keys are managed on the [https://secure.barion.com Barion secure site], on the shop&#039;s security page (Shops -&amp;gt; Actions -&amp;gt; Settings -&amp;gt; Security -&amp;gt; Manage).&lt;br /&gt;
&lt;br /&gt;
* A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.&lt;br /&gt;
* A new key is created &amp;lt;b&amp;gt;inactive&amp;lt;/b&amp;gt;. Mark it as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; when your server is ready.&lt;br /&gt;
* At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.&lt;br /&gt;
* The active key cannot be deleted. Deactivate it, or activate the other key, first.&lt;br /&gt;
* The key is shown and copied as a base64 string. &amp;lt;b&amp;gt;Decode it from base64&amp;lt;/b&amp;gt; and use the resulting 64 bytes as the HMAC key.&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=Keep the HMAC key on your server only, like the POS key. If you think a key is compromised, generate a new one, switch to it and delete the old one.|color=#038Ed3}}&lt;br /&gt;
&lt;br /&gt;
== Signature headers ==&lt;br /&gt;
&lt;br /&gt;
Every signed request and response carries these three headers:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Header !! Content&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-timestamp&#039;&#039;&#039; || The time of signing as a Unix timestamp in seconds (UTC), e.g. &amp;lt;code&amp;gt;1760968800&amp;lt;/code&amp;gt;.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-nonce&#039;&#039;&#039; || A GUID, e.g. &amp;lt;code&amp;gt;3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84&amp;lt;/code&amp;gt;. In a request it must be new for every request. In a response it is the nonce of the request being answered.&lt;br /&gt;
|-&lt;br /&gt;
| &#039;&#039;&#039;x-signature-sha512&#039;&#039;&#039; || The HMAC-SHA512 of the signed text (see below), base64-encoded.&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== The signed text ==&lt;br /&gt;
&lt;br /&gt;
The signature is computed over a text made of the following parts, joined with a single line feed character (&amp;lt;code&amp;gt;\n&amp;lt;/code&amp;gt;, LF, no carriage return). The text is UTF-8 encoded before signing.&lt;br /&gt;
&lt;br /&gt;
=== Requests (your API requests and Barion&#039;s IPN) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;HTTP method&#039;&#039;&#039;: in upper case, e.g. &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;path and query&#039;&#039;&#039;: the path and the query string of the URL as it appears on the request line, e.g. &amp;lt;code&amp;gt;/v2/Payment/Start&amp;lt;/code&amp;gt; or &amp;lt;code&amp;gt;/v4/Payment/GetPaymentState?PaymentId=...&amp;lt;/code&amp;gt;. The scheme, the host and the port are not part of it.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact request body, byte for byte as it is sent. For a request without a body (e.g. &amp;lt;code&amp;gt;GET&amp;lt;/code&amp;gt;) it is an empty string, so the text ends with the line feed after the path.&lt;br /&gt;
&lt;br /&gt;
=== Responses (Barion&#039;s answers to your signed requests) ===&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
* &#039;&#039;&#039;x-nonce&#039;&#039;&#039;: the nonce of &amp;lt;b&amp;gt;your request&amp;lt;/b&amp;gt; that the response answers. It is echoed back in the response&#039;s &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; header, and binds the response to your request.&lt;br /&gt;
* &#039;&#039;&#039;HTTP status code&#039;&#039;&#039;: as a number, e.g. &amp;lt;code&amp;gt;200&amp;lt;/code&amp;gt;.&lt;br /&gt;
* &#039;&#039;&#039;body&#039;&#039;&#039;: the exact response body as received.&lt;br /&gt;
&lt;br /&gt;
Responses are signed only when the request was signed correctly.&lt;br /&gt;
&lt;br /&gt;
== Signing your API requests ==&lt;br /&gt;
&lt;br /&gt;
# Generate a new GUID for &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and take the current Unix time in seconds for &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;.&lt;br /&gt;
# Build the signed text from the timestamp, the nonce, the method, the path and query, and the exact body you are going to send.&lt;br /&gt;
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.&lt;br /&gt;
# Send the request with the &amp;lt;code&amp;gt;x-pos-key&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
&lt;br /&gt;
Barion checks that:&lt;br /&gt;
* the timestamp is within 5 minutes of the server time, in either direction,&lt;br /&gt;
* the nonce has not been used by the shop before (so a captured request cannot be replayed),&lt;br /&gt;
* the signature matches the request signed with the active key.&lt;br /&gt;
&lt;br /&gt;
== Verifying Barion&#039;s messages ==&lt;br /&gt;
&lt;br /&gt;
For a response to your request, and for a payment IPN message:&lt;br /&gt;
# Read the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers.&lt;br /&gt;
# Build the signed text: for a response with the response&#039;s status code and body, for an IPN with &amp;lt;code&amp;gt;POST&amp;lt;/code&amp;gt;, the path and query of your callback URL as it was called (including the &amp;lt;code&amp;gt;paymentId&amp;lt;/code&amp;gt; query parameter) and the request body.&lt;br /&gt;
# Compute the HMAC-SHA512 with your active key and compare it with &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt;. Use a constant-time comparison.&lt;br /&gt;
# Reject the message if the signature does not match. We also recommend rejecting it if the timestamp is more than a few minutes off your server time, and, for an IPN, if you have already processed its nonce.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
== Example ==&lt;br /&gt;
&lt;br /&gt;
Signing a request in C#:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;pre&amp;gt;&lt;br /&gt;
using System;&lt;br /&gt;
using System.Security.Cryptography;&lt;br /&gt;
using System.Text;&lt;br /&gt;
&lt;br /&gt;
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)&lt;br /&gt;
{&lt;br /&gt;
    string text = string.Join(&amp;quot;\n&amp;quot;, timestamp, nonce, method.ToUpperInvariant(), pathAndQuery, body ?? &amp;quot;&amp;quot;);&lt;br /&gt;
&lt;br /&gt;
    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))&lt;br /&gt;
    {&lt;br /&gt;
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&lt;br /&gt;
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();&lt;br /&gt;
string nonce = Guid.NewGuid().ToString();&lt;br /&gt;
string body = &amp;quot;{\&amp;quot;PaymentRequestId\&amp;quot;:\&amp;quot;...\&amp;quot;}&amp;quot;;&lt;br /&gt;
string signature = Sign(hmacKey, timestamp, nonce, &amp;quot;POST&amp;quot;, &amp;quot;/v2/Payment/Start&amp;quot;, body);&lt;br /&gt;
&lt;br /&gt;
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}&lt;br /&gt;
&amp;lt;/pre&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Rotating the key ==&lt;br /&gt;
&lt;br /&gt;
# Generate a second key on the security page. The current key keeps working.&lt;br /&gt;
# Prepare your server to sign with the new key and to verify with it.&lt;br /&gt;
# Mark the new key as &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt;. From that moment Barion signs with the new key and checks your requests against it, so your server must already sign with the new key.&lt;br /&gt;
# Once your server no longer uses the old key, delete the old key.&lt;br /&gt;
&lt;br /&gt;
== Turning signing off ==&lt;br /&gt;
&lt;br /&gt;
Untick &amp;lt;i&amp;gt;Active&amp;lt;/i&amp;gt; on the active key. Barion stops signing its messages right away and no longer checks the signature of your requests. If your server rejects unsigned messages, it will reject Barion&#039;s IPN messages and responses too.&lt;br /&gt;
&lt;br /&gt;
== Errors ==&lt;br /&gt;
&lt;br /&gt;
If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status &amp;lt;code&amp;gt;401&amp;lt;/code&amp;gt; and one of these errors:&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
! Error code !! Meaning&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;MissingSignature&amp;lt;/code&amp;gt; || One or more of the &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt;, &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;x-signature-sha512&amp;lt;/code&amp;gt; headers is missing.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidNonce&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; is not a GUID.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidTimestamp&amp;lt;/code&amp;gt; || &amp;lt;code&amp;gt;x-timestamp&amp;lt;/code&amp;gt; is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;InvalidSignature&amp;lt;/code&amp;gt; || The signature does not match the request signed with the shop&#039;s active HMAC key.&lt;br /&gt;
|-&lt;br /&gt;
| &amp;lt;code&amp;gt;ReplayedRequest&amp;lt;/code&amp;gt; || A request with this &amp;lt;code&amp;gt;x-nonce&amp;lt;/code&amp;gt; has already been received.&lt;br /&gt;
|}&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
	<entry>
		<id>https://docs.barion.com/index.php?title=Token_payment_3D_Secure&amp;diff=4948</id>
		<title>Token payment 3D Secure</title>
		<link rel="alternate" type="text/html" href="https://docs.barion.com/index.php?title=Token_payment_3D_Secure&amp;diff=4948"/>
		<updated>2026-10-07T13:40:57Z</updated>

		<summary type="html">&lt;p&gt;Vargaj@barion.dev: /* Changing the funding source */&lt;/p&gt;
&lt;hr /&gt;
&lt;div&gt;{{PageTitle|title=Token Payment with 3D Secure}}&lt;br /&gt;
__TOC__&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
This payment scenario allows the integrator shop to register a token for a customer (and a funding source) in the Barion system and then, later on, using this token, charge the customer without redirecting her to the Barion Smart Gateway UI. The user may be present at the site of the merchant or she can be off-session as well, so the merchant can charge her e.g. for subscriptions. This means that the customer authorizes the shop to charge her card or Barion balance without typing in the card information or Barion login again.&lt;br /&gt;
&lt;br /&gt;
[[File:3ds-recurring.png|1500px]]&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=Premium feature|text=If you want to use this scenario, you have to specifically request it from Barion.|color=#1993c7}}&lt;br /&gt;
&lt;br /&gt;
= Token payment scenarios =&lt;br /&gt;
Token payment can be used in three use cases: &lt;br /&gt;
* &#039;&#039;&#039;Customer Initiated Payments&#039;&#039;&#039;: when the user is present on the website of the merchant and she decides to pay :&lt;br /&gt;
** &#039;&#039;&#039;OneClick payment&#039;&#039;&#039;: the user is charged upon her request initiated on the website of the merchant. Subsequent payments are subject to PSD2 SCA and as the user is present, she has to go through the authentication process.&lt;br /&gt;
* &#039;&#039;&#039;Merchant Initiated Payments&#039;&#039;&#039;: when the merchant initiates the payment without the user being present. It has two subtypes:&lt;br /&gt;
** &#039;&#039;&#039;Recurring payment&#039;&#039;&#039;: the user is charged with the same amount on a regular basis, typically in case of subscriptions. Subsequent payments are exempted from PSD2 SCA, but liability still shifts to the card issuer.&lt;br /&gt;
** &#039;&#039;&#039;MIT (merchant-initiated transaction)&#039;&#039;&#039;: the user is charged on an irregular basis and/or with a different amount. Subsequent payments of this type are excluded from PSD2 SCA, the liability is on the merchant.&lt;br /&gt;
&lt;br /&gt;
== Customer participation ==&lt;br /&gt;
&lt;br /&gt;
Since the token scenario is suitable for both customer and merchant-initiated payments here is a comparison about who starts the payment. This includes the regular, non-tokenized payment scenario as well:&lt;br /&gt;
&lt;br /&gt;
{|class=wikitable&lt;br /&gt;
|-&lt;br /&gt;
! rowspan=&amp;quot;2&amp;quot; | Scenario&lt;br /&gt;
! colspan=&amp;quot;2&amp;quot; | Initial payment&lt;br /&gt;
! colspan=&amp;quot;2&amp;quot; | Subsequent payments&lt;br /&gt;
|-&lt;br /&gt;
! Customer present&lt;br /&gt;
! Customer at Barion Smart GW &lt;br /&gt;
! Customer present&lt;br /&gt;
! Customer at Barion Smart GW&lt;br /&gt;
|-&lt;br /&gt;
| Non token (regular) payment || YES || YES || YES || YES &lt;br /&gt;
|-&lt;br /&gt;
| OneClick payment || YES || YES/NO&amp;lt;sup&amp;gt;1&amp;lt;/sup&amp;gt; || YES || style=&amp;quot;background:#FFE2C4&amp;quot; | NO &lt;br /&gt;
|-&lt;br /&gt;
| Recurring payment || YES || YES/NO&amp;lt;sup&amp;gt;1&amp;lt;/sup&amp;gt; || style=&amp;quot;background:#FFE2C4&amp;quot; | NO || style=&amp;quot;background:#FFE2C4&amp;quot; | NO &lt;br /&gt;
|-&lt;br /&gt;
| MIT || YES || YES/NO&amp;lt;sup&amp;gt;1&amp;lt;/sup&amp;gt; || style=&amp;quot;background:#FFE2C4&amp;quot; | NO || style=&amp;quot;background:#FFE2C4&amp;quot; | NO &lt;br /&gt;
|-&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
&amp;lt;div style=&amp;quot;border: 1px solid #aaa; background-color:#eee; font-size: 0.8em; padding:5px 10px; display:inline-block;&amp;quot;&amp;gt;&lt;br /&gt;
&amp;lt;sup&amp;gt;1&amp;lt;/sup&amp;gt; Token payment scenarios can be initiated with already registered &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; as well, in this case, the customer may remain on the merchant&#039;s site. &lt;br /&gt;
&amp;lt;/div&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Requirements for the scenarios ==&lt;br /&gt;
&lt;br /&gt;
These token payment scenarios have different requirements, the table below summarizes the key differences.&lt;br /&gt;
&lt;br /&gt;
{|class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|-&lt;br /&gt;
! Scenario&lt;br /&gt;
! Payment amount&lt;br /&gt;
! Payment frequency&lt;br /&gt;
! Liability in case of fraud&lt;br /&gt;
|-&lt;br /&gt;
| One-click payment with 3DS || Various || Various || Card issuer&lt;br /&gt;
|-&lt;br /&gt;
| Recurring payment || Subsequent amounts must be equal or less than the initial amount  || Initial payment must define a minimum amount of days to wait between charges || Card issuer &lt;br /&gt;
|-&lt;br /&gt;
| Merchant initiated payment || Various  || Various || Merchant&lt;br /&gt;
|- &lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
== 3DS authentication of the payer ==&lt;br /&gt;
&lt;br /&gt;
The new more secure 3DS v2 authentication must be performed for every online card payment. These token payment scenarios also have to use this new secure way of authentication. &lt;br /&gt;
The initial payment of a token scenario must be authenticated every time although the subsequent payments may be exempted in certain cases. &lt;br /&gt;
&lt;br /&gt;
Here is a table to compare the 3DS authentication requirements:&lt;br /&gt;
&lt;br /&gt;
{|class=&amp;quot;wikitable&amp;quot;&lt;br /&gt;
|-&lt;br /&gt;
! Scenario&lt;br /&gt;
! Initial payment&lt;br /&gt;
! Subsequent payments&lt;br /&gt;
|-&lt;br /&gt;
| One-click payment || ✔️ || ✔️&lt;br /&gt;
|-&lt;br /&gt;
| Recurring payment || ✔️ || &lt;br /&gt;
|-&lt;br /&gt;
| Merchant initiated payment || ✔️ || &lt;br /&gt;
|-&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;IMPORTANT:&#039;&#039; When performing subsequent One-click payments with the &amp;lt;code&amp;gt;ChallengePreference&amp;lt;/code&amp;gt; parameter set to &amp;lt;code&amp;gt;NoChallengeNeeded&amp;lt;/code&amp;gt; (indicating a request for Transaction Risk Analysis), only a fraud analysis is performed, and the customer is not required to undergo a 3DS challenge.&lt;br /&gt;
&lt;br /&gt;
== Real life examples ==&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Phone bill&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
The payer has a usage-based phone subscription that wants to pay without being present for every charge. They authorize the phone company to charge her card every month.&lt;br /&gt;
* Scenario: Merchant Initiated Transaction&lt;br /&gt;
* Explanation: Despite the frequency of the charges is monthly, the amount of the subsequent payments may exceed the initial payment.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;TV subscription&#039;&#039;&#039; &lt;br /&gt;
&lt;br /&gt;
Payer subscribes to online streaming of a television channel. She authorizes the tv company to charge her card every month. The subscription fee is the same for every month.&lt;br /&gt;
* Scenario: Recurring payment&lt;br /&gt;
* Explanation: The amount of the subsequent payments will not exceed the initial payment and the charge is regularly monthly-based.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Bookclub with &amp;quot;free first month&amp;quot; bonus&#039;&#039;&#039; &lt;br /&gt;
&lt;br /&gt;
Payer subscribes to a book renting service. he authorizes the book club to charge her card for a selection of books each month. The subscription fee is the same for every month however, the first month is free. To ensure the subscription the service requires her to register her card details.&lt;br /&gt;
* Scenario: Merchant Initiated Transaction&lt;br /&gt;
* Explanation: Despite the frequency of the charges is monthly, and the fee will stay the same, the initial payment is zero. So the amount of the next payment will exceed the initial payment.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Online food delivery service&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
The food delivery company wants to provide a quick and easy experience for its customer. They decide that the order will be quicker if the customers don&#039;t leave the website to pay for the goods.&lt;br /&gt;
* Scenario: OneClick payment&lt;br /&gt;
* Explanation: The customer will always be there so the other two scenarios are not available.&lt;br /&gt;
&lt;br /&gt;
== How to decide ==&lt;br /&gt;
&lt;br /&gt;
To help you decide on a suitable scenario, please use the decision graph below:&lt;br /&gt;
&lt;br /&gt;
[[File:3ds-recurrencetype-decision.png|520px]]&lt;br /&gt;
&lt;br /&gt;
= Prerequisites =&lt;br /&gt;
To be able to integrate your webshop with the Barion Payment Gateway: &lt;br /&gt;
* You must [[Creating_an_account|register a Barion wallet]] at the Barion website or in the Sandbox environment. Learn more about the Sandbox environment [[Sandbox|here]].&lt;br /&gt;
* For this wallet you have to [[Creating_a_shop|create a shop]] which should be approved by Barion.&lt;br /&gt;
* For every currency you plan to conduct payments in you have to make sure there is an account created in your Barion wallet. This means that if you plan to have USD payments then there should be a USD account created in your wallet.&lt;br /&gt;
* To make sure every corner case scenario works for your webshop it is best to top up that account with a small amount (approx. 5-10EUR or your choice of currency around the same value).&lt;br /&gt;
* For the technical communication guide please read this: [[Calling_the_API|Calling the API]]&lt;br /&gt;
&lt;br /&gt;
= The payment process =&lt;br /&gt;
&lt;br /&gt;
The process is divided into two major steps:&lt;br /&gt;
&amp;lt;ol&amp;gt;&lt;br /&gt;
   &amp;lt;li&amp;gt;[[#Step 1:  Creating the funding source token|Creating the token]] that represents one of the customer&#039;s funding sources (bank card or e-money wallet)&lt;br /&gt;
      &amp;lt;ol&amp;gt;&lt;br /&gt;
         &amp;lt;li&amp;gt;Preparing the payment via the Barion API&amp;lt;/li&amp;gt;&lt;br /&gt;
         &amp;lt;li&amp;gt;Redirecting the customer to the Barion Smart Gateway to select a funding source&amp;lt;/li&amp;gt;&lt;br /&gt;
         &amp;lt;li&amp;gt;Processing the callback and requesting information about the result of the payment&amp;lt;/li&amp;gt;&lt;br /&gt;
      &amp;lt;/ol&amp;gt;&lt;br /&gt;
   &amp;lt;/li&amp;gt;&lt;br /&gt;
   &amp;lt;li&amp;gt;[[#Step 2: Using the token|Using the registered token]] to charge the customer&amp;lt;/li&amp;gt;&lt;br /&gt;
   &lt;br /&gt;
&amp;lt;/ol&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Step 1:  Creating the funding source token ==&lt;br /&gt;
To be able to use a token payment scenario first the merchant has to register the token with Barion. The merchant has to make sure that the customer is well aware of the fact that they are giving consent to a tokenized payment. The Barion Smart Gateway UI does not indicate in any way that the payment is a token payment.&lt;br /&gt;
&lt;br /&gt;
The token is registered to the shop and not to the merchant&#039;s Barion account. So if the merchant has multiple shops in its Barion account, the registered tokens can not be shared among them even if the customer is the same. If you want to use tokens in multiple shops, please contact Barion in the Customer center.&lt;br /&gt;
&lt;br /&gt;
=== 1.1 Preparing the payment===&lt;br /&gt;
&lt;br /&gt;
The token registration is basically a [[Responsive_web_payment|normal payment]] with three extra properties in the [[Payment-Start-v2|Payment/Start]] request:&lt;br /&gt;
* InitiateRecurrence&lt;br /&gt;
* RecurrenceId&lt;br /&gt;
* RecurrenceType&lt;br /&gt;
&lt;br /&gt;
==== InitiateRecurrence====&lt;br /&gt;
&lt;br /&gt;
The &amp;lt;code&amp;gt;InitiateRecurrence&amp;lt;/code&amp;gt; is a bool property. If you set it to &#039;&#039;&#039;true&#039;&#039;&#039; then the payment gateway will consider the payment as a token registration. &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;This happens even if the customer is already has a registered token, so you are able to re-register a funding source or even a customer. &#039;&#039;&lt;br /&gt;
&lt;br /&gt;
==== RecurrenceId ====&lt;br /&gt;
The next required property for a token registration is the token itself. This is generated by the shop and has to be unique for every registration. The token should be specified in the &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; property of the [[Payment-Start-v2|Payment/Start]] request. This token must be saved in the webshops database. A &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; token represents the funding source (bank card or Barion balance) of a customer. Since a customer can have multiple cards and accounts as a funding source make sure that in the webshop&#039;s system multiple tokens can belong to a single customer.&lt;br /&gt;
&lt;br /&gt;
==== RecurrenceType ====&lt;br /&gt;
The third required property is the [[RecurrenceType|Recurrence Type]]. This specifies the scenario. In case of Recurring Payment &amp;lt;code&amp;gt;PurchaseInformation.RecurringExpiry&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;PurchaseInformation.RecurringFrequency&amp;lt;/code&amp;gt; must also be set.&lt;br /&gt;
&lt;br /&gt;
==== Example JSON request for a Merchant Initiated Payment scenario ====&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=json line highlight=&amp;quot;5-7&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;POSKey&amp;quot;: &amp;quot;[[SECRET_POS_KEY]]&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;EXMPLSHOP-PM-001&amp;quot;,&lt;br /&gt;
    &amp;quot;InitiateRecurrence&amp;quot;: true,&lt;br /&gt;
    &amp;quot;RecurrenceId&amp;quot;: &amp;quot;SHOP-XMLP-TOKEN-ABC-123&amp;quot;,&lt;br /&gt;
    &amp;quot;RecurrenceType&amp;quot;: &amp;quot;MerchantInitiatedPayment&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSources&amp;quot;: [&amp;quot;All&amp;quot;],&lt;br /&gt;
    &amp;quot;GuestCheckOut&amp;quot; : true,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;EXMPLSHOP-PM-001/TR001&amp;quot;,&lt;br /&gt;
            &amp;quot;Payee&amp;quot;: &amp;quot;[[MERCHANTS_BARION_EMAIL]]&amp;quot;,&lt;br /&gt;
            &amp;quot;Total&amp;quot;: 25.2,&lt;br /&gt;
            &amp;quot;Comment&amp;quot;: &amp;quot;Subscription fee for the first month&amp;quot;,&lt;br /&gt;
            &amp;quot;Items&amp;quot;: [&lt;br /&gt;
                {&lt;br /&gt;
                    &amp;quot;Name&amp;quot;: &amp;quot;Website subscription&amp;quot;,&lt;br /&gt;
                    &amp;quot;Description&amp;quot;: &amp;quot;Website subscription for one month&amp;quot;,&lt;br /&gt;
                    &amp;quot;Quantity&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;Unit&amp;quot;: &amp;quot;month&amp;quot;,&lt;br /&gt;
                    &amp;quot;UnitPrice&amp;quot;: 25.2,&lt;br /&gt;
                    &amp;quot;ItemTotal&amp;quot;: 25.2,&lt;br /&gt;
                    &amp;quot;SKU&amp;quot;: &amp;quot;EXMPLSHOP/SKU/PHC-01&amp;quot;&lt;br /&gt;
                }&lt;br /&gt;
            ]&lt;br /&gt;
        }&lt;br /&gt;
    ]&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The response will be the same as to a [[Responsive_web_payment#Processing_the_successful_response|basic &#039;&#039;&#039;Immediate&#039;&#039;&#039; scenario]]. The &amp;lt;code&amp;gt;RecurrenceResult&amp;lt;/code&amp;gt; property at this point is &#039;&#039;&#039;None&#039;&#039;&#039; since the token is not registered to a funding source yet.&lt;br /&gt;
&lt;br /&gt;
==== Example JSON request for a Recurring Payment scenario ====&lt;br /&gt;
&lt;br /&gt;
The &#039;&#039;&#039;Recurring Payment&#039;&#039;&#039; scenario has some extra restrictions. The merchant has to specify two additional properties in the [[Payment-Start-v2|Payment/Start]] request:&lt;br /&gt;
* &amp;lt;code&amp;gt;RecurringExpiry&amp;lt;/code&amp;gt;: The date after subsequent charges should not be accepted.&lt;br /&gt;
* &amp;lt;code&amp;gt;RecurringFrequency&amp;lt;/code&amp;gt;: The minimum days the merchant has to wait between payments.&lt;br /&gt;
&lt;br /&gt;
Both properties are located in the [[PurchaseInformation]] property and must be specified if this scenario is selected.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=json line highlight=&amp;quot;5-7, 30-33&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;POSKey&amp;quot;: &amp;quot;[[SECRET_POS_KEY]]&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;EXMPLSHOP-PM-001&amp;quot;,&lt;br /&gt;
    &amp;quot;InitiateRecurrence&amp;quot;: true,&lt;br /&gt;
    &amp;quot;RecurrenceId&amp;quot;: &amp;quot;SHOP-XMLP-TOKEN-ABC-123&amp;quot;,&lt;br /&gt;
    &amp;quot;RecurrenceType&amp;quot;: &amp;quot;RecurringPayment&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSources&amp;quot;: [&amp;quot;All&amp;quot;],&lt;br /&gt;
    &amp;quot;GuestCheckOut&amp;quot; : true,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;EXMPLSHOP-PM-001/TR001&amp;quot;,&lt;br /&gt;
            &amp;quot;Payee&amp;quot;: &amp;quot;[[MERCHANTS_BARION_EMAIL]]&amp;quot;,&lt;br /&gt;
            &amp;quot;Total&amp;quot;: 25.2,&lt;br /&gt;
            &amp;quot;Comment&amp;quot;: &amp;quot;Subscription fee for the first month&amp;quot;,&lt;br /&gt;
            &amp;quot;Items&amp;quot;: [&lt;br /&gt;
                {&lt;br /&gt;
                    &amp;quot;Name&amp;quot;: &amp;quot;Website subscription&amp;quot;,&lt;br /&gt;
                    &amp;quot;Description&amp;quot;: &amp;quot;Website subscription for one month&amp;quot;,&lt;br /&gt;
                    &amp;quot;Quantity&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;Unit&amp;quot;: &amp;quot;month&amp;quot;,&lt;br /&gt;
                    &amp;quot;UnitPrice&amp;quot;: 25.2,&lt;br /&gt;
                    &amp;quot;ItemTotal&amp;quot;: 25.2,&lt;br /&gt;
                    &amp;quot;SKU&amp;quot;: &amp;quot;EXMPLSHOP/SKU/PHC-01&amp;quot;&lt;br /&gt;
                }&lt;br /&gt;
            ]&lt;br /&gt;
        }&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;PurchaseInformation&amp;quot;:{&lt;br /&gt;
        &amp;quot;RecurringFrequency&amp;quot;: 10,&lt;br /&gt;
        &amp;quot;RecurringExpiry&amp;quot;: &amp;quot;2022-10-01&amp;quot;&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== Possible error responses ====&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable api-table&amp;quot;&lt;br /&gt;
! Error code || Description&lt;br /&gt;
|-&lt;br /&gt;
| RecurringPaymentNotAllowed || The token payment is not allowed for the shop identified by the &#039;&#039;&#039;POSKey&#039;&#039;&#039;. Contact Barion to request this feature.&lt;br /&gt;
|-&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
=== 1.2 Redirecting the customer to the Barion Smart Gateway to select a funding source ===&lt;br /&gt;
&lt;br /&gt;
After a successful payment preparation, the customer is redirected to the secure Barion Smart Gateway to choose a funding source. The funding source the customer selects will be registered to the token. The funding source can either be a Barion e-money balance or a bank card. This means that even though the customer may own multiple cards only the one that was registered to the token can be used for future token payments. To change the funding source attached to the token a new registration should be requested.&lt;br /&gt;
&lt;br /&gt;
=== 1.3 Processing the callback and requesting information about the result of the payment ===&lt;br /&gt;
&lt;br /&gt;
When the payment is completed (either successfully or unsuccessfully) a callback message is sent to the merchant&#039;s system. Once received a [[Payment-PaymentState-v4|/v4/Payment/&amp;lt;PaymentId&amp;gt;/PaymentState]] request must be sent to the Barion API. On how to implement this please read the article about the  [[Callback_mechanism|Callback mechanism]].&lt;br /&gt;
&lt;br /&gt;
The full response of the GetPaymentState request depends on the payment scenario and the structure of the payment. When it comes to token payment there are several properties to look out for. &lt;br /&gt;
* In case the &amp;lt;code&amp;gt;Status&amp;lt;/code&amp;gt; is &#039;&#039;&#039;Succeeded&#039;&#039;&#039; the funding source token is registered and ready to use.&lt;br /&gt;
* The &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; contains the ID of the token process. This specifies the nature of the token payment. &lt;br /&gt;
&lt;br /&gt;
==== TraceId ====&lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=NOTE|text=TraceId exists only in case of a bank card payment (FundingSource=BankCard).|color=#FFAC1C}}&lt;br /&gt;
&lt;br /&gt;
In case of Recurring payment or Merchant initiated payment scenarios the [[Payment-PaymentState-v4|PaymentState]] response returns an additional field called &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt;. The value of this property is generated by the card issuer and is up to a 100 characters, and should be left intact (whitespaces and 0s can&#039;t be trimmed). The merchant has to save it and submit it in all subsequent Recurring or Merchant initiated payments of the same type, otherwise, the payments can be declined by the issuer. The &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; represents the first, customer-present payment and helps the issuer to connect subsequent payments to this initial payment.&lt;br /&gt;
&lt;br /&gt;
====Example GetPaymentState response====&lt;br /&gt;
&amp;lt;source lang=json line highlight=&amp;quot;8, 11-12&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;PaymentId&amp;quot;: &amp;quot;2a9f3260bc2feb118bc3001dd8b71cc4&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;EXMPLSHOP-PM-001&amp;quot;,&lt;br /&gt;
    &amp;quot;OrderNumber&amp;quot;: null,&lt;br /&gt;
    &amp;quot;POSId&amp;quot;: &amp;quot;[[SHOPS_PUBLIC_KEY]]&amp;quot;,&lt;br /&gt;
    &amp;quot;POSName&amp;quot;: &amp;quot;[[MERCHANTS_BARION_SHOPNAME]]&amp;quot;,&lt;br /&gt;
    &amp;quot;POSOwnerEmail&amp;quot;: &amp;quot;[[MERCHANTS_BARION_EMAIL]]&amp;quot;,&lt;br /&gt;
    &amp;quot;Status&amp;quot;: &amp;quot;Succeeded&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSource&amp;quot;: &amp;quot;BankCard&amp;quot;,&lt;br /&gt;
    &amp;quot;RecurrenceType&amp;quot;: &amp;quot;MerchantInitiatedPayment&amp;quot;,&lt;br /&gt;
    &amp;quot;TraceId&amp;quot;: &amp;quot;FGTRR55322843442124780&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingInformation&amp;quot;: {&lt;br /&gt;
        &amp;quot;BankCard&amp;quot;: {&lt;br /&gt;
            &amp;quot;MaskedPan&amp;quot;: &amp;quot;0425&amp;quot;,&lt;br /&gt;
            &amp;quot;BankCardType&amp;quot;: &amp;quot;Visa&amp;quot;,&lt;br /&gt;
            &amp;quot;ValidThruYear&amp;quot;: &amp;quot;2020&amp;quot;,&lt;br /&gt;
            &amp;quot;ValidThruMonth&amp;quot;: &amp;quot;12&amp;quot;&lt;br /&gt;
        },&lt;br /&gt;
        &amp;quot;AuthorizationCode&amp;quot;: &amp;quot;512244&amp;quot;,&lt;br /&gt;
        &amp;quot;ProcessResult&amp;quot;: &amp;quot;Successful&amp;quot;&lt;br /&gt;
    },&lt;br /&gt;
    &amp;quot;AllowedFundingSources&amp;quot;: [&lt;br /&gt;
        &amp;quot;All&amp;quot;&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;GuestCheckout&amp;quot;: true,&lt;br /&gt;
    &amp;quot;CreatedAt&amp;quot;: &amp;quot;2020-11-26T07:52:48.9Z&amp;quot;,&lt;br /&gt;
    &amp;quot;ValidUntil&amp;quot;: &amp;quot;2020-11-26T08:22:48.9Z&amp;quot;,&lt;br /&gt;
    &amp;quot;CompletedAt&amp;quot;: &amp;quot;2020-11-26T08:11:54.118Z&amp;quot;,&lt;br /&gt;
    &amp;quot;ReservedUntil&amp;quot;: null,&lt;br /&gt;
    &amp;quot;DelayedCaptureUntil&amp;quot;: null,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
           ...&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;Total&amp;quot;: 25.20,&lt;br /&gt;
    &amp;quot;SuggestedLocale&amp;quot;: &amp;quot;hu-HU&amp;quot;,&lt;br /&gt;
    &amp;quot;FraudRiskScore&amp;quot;: null,&lt;br /&gt;
    &amp;quot;RedirectUrl&amp;quot;: &amp;quot;https://merchanturl/Redirect?paymentId=2a9f3260bc2feb118bc3001dd8b71cc4&amp;quot;,&lt;br /&gt;
    &amp;quot;CallbackUrl&amp;quot;: &amp;quot;https://merchanturl/Callback?paymentId=2a9f3260bc2feb118bc3001dd8b71cc4&amp;quot;,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Errors&amp;quot;: []&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== Displaying the funding source in a GUI ====&lt;br /&gt;
We strongly advise saving the complete response for future reference. The &amp;lt;code&amp;gt;FundingSource&amp;lt;/code&amp;gt; field tells if the funding source is a Barion balance or a card. If it is a card, it is useful to save [[FundingInformation]] for displaying it for the user, when requesting future payments. The usual way to display funding sources is to show the last 4 digits of the card, with 4 stars, eg: *** 1234. The card used can be obtained from FundingInformation&#039;s [[BankCard]] field. The [[CardType]] field can be used to display the appropriate card logo. You can even show, if the card is expired, and offer to register another one.&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039; FundingInformation part of the GetPaymentState response &#039;&#039;&#039;&lt;br /&gt;
&amp;lt;source lang=json&amp;gt;&lt;br /&gt;
...&lt;br /&gt;
    &amp;quot;FundingInformation&amp;quot;: {&lt;br /&gt;
        &amp;quot;BankCard&amp;quot;: {&lt;br /&gt;
            &amp;quot;MaskedPan&amp;quot;: &amp;quot;0425&amp;quot;,&lt;br /&gt;
            &amp;quot;BankCardType&amp;quot;: &amp;quot;Visa&amp;quot;,&lt;br /&gt;
            &amp;quot;ValidThruYear&amp;quot;: &amp;quot;2020&amp;quot;,&lt;br /&gt;
            &amp;quot;ValidThruMonth&amp;quot;: &amp;quot;12&amp;quot;&lt;br /&gt;
        },&lt;br /&gt;
        &amp;quot;AuthorizationCode&amp;quot;: &amp;quot;512244&amp;quot;,&lt;br /&gt;
        &amp;quot;ProcessResult&amp;quot;: &amp;quot;Successful&amp;quot;&lt;br /&gt;
    }&lt;br /&gt;
...&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This can be displayed for example as &amp;lt;code&amp;gt;VISA **** 0425 (12/20)&amp;lt;/code&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This is a request-response diagram of the token registration process:&lt;br /&gt;
 &lt;br /&gt;
[[File:Token_payment_initiation.jpg]]&lt;br /&gt;
&lt;br /&gt;
= Step 2: Using the token =&lt;br /&gt;
&lt;br /&gt;
To use an already registered token for a payment, you have to use the same [[Payment-Start-v2|/Payment/Start]] API endpoint but the &amp;lt;code&amp;gt;InitiateRecurrence&amp;lt;/code&amp;gt; should be set to &amp;lt;code&amp;gt;false&amp;lt;/code&amp;gt;. This tells the Barion API to use the token for payment instead of only registering it. The token should be specified in the &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; property. To be able to use a token, the initial payment must be in a successful state.&lt;br /&gt;
&lt;br /&gt;
At this point, the merchant has to decide whether this subsequent payment is used for the same token payment scenario or something changed. This is important because the &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; can only be used for the same scenario, otherwise, the card issuer will decline the charge.&lt;br /&gt;
A &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; can only be used again if:&lt;br /&gt;
* the funding source is the same (technically the &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; is the same)&lt;br /&gt;
* the token payment scenario is the same (technically the &amp;lt;code&amp;gt;RecurrenceType&amp;lt;/code&amp;gt; is the same)&lt;br /&gt;
* this subsequent request complies with the scenario restrictions (eg: in case of recurring payment the amount of the subsequent payment does not exceed the initial amount)&lt;br /&gt;
&lt;br /&gt;
If the funding source changes, new &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; must be requested. The process to do that is [[#Changing the funding source|described in detail here]]. If the funding source stays the same but the scenario changes or the restrictions are no longer met new &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; must be requested. The process to do that is [[#Changing the token payment scenario with an existing token|described here]].&lt;br /&gt;
&lt;br /&gt;
== Subsequent payments in case of Recurring payment scenario ==&lt;br /&gt;
&lt;br /&gt;
In this case, three extra conditions must be met:&lt;br /&gt;
* the amount of the subsequent payment must not be higher than the initial amount&lt;br /&gt;
* at least that much days must be spent as defined in the initial &amp;lt;code&amp;gt;RecurringFrequency&amp;lt;/code&amp;gt; property&lt;br /&gt;
* the date of the payment must not exceed the day specified in the initial &amp;lt;code&amp;gt;RecurringExpiry&amp;lt;/code&amp;gt; property&lt;br /&gt;
&lt;br /&gt;
Please be aware that in case any of these are no longer valid the merchant has to request a new &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; as [[#Changing the token payment scenario with an existing token|described here]]. &lt;br /&gt;
&lt;br /&gt;
{{NotificationBox|title=IMPORTANT|text=These conditions are not enforced by the Barion system so the violation of them will result in a declined charge.|color=#FF7A3D}}&lt;br /&gt;
&lt;br /&gt;
Payment/start must not include the &amp;lt;code&amp;gt;RecurringFrequency&amp;lt;/code&amp;gt; and &amp;lt;code&amp;gt;RecurringExpiry&amp;lt;/code&amp;gt; properties (since they are already fixed during the initial payment).&lt;br /&gt;
&lt;br /&gt;
==== Example payment/start of a subsequent Recurring payment ====&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=json line highlight=&amp;quot;5-8&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;POSKey&amp;quot;: &amp;quot;[[SECRET_POS_KEY]]&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;EXMPLSHOP-PM-002&amp;quot;,&lt;br /&gt;
    &amp;quot;InitiateRecurrence&amp;quot;: false,&lt;br /&gt;
    &amp;quot;RecurrenceId&amp;quot;: &amp;quot;SHOP-XMLP-TOKEN-ABC-123&amp;quot;,&lt;br /&gt;
    &amp;quot;RecurrenceType&amp;quot;: &amp;quot;RecurringPayment&amp;quot;,&lt;br /&gt;
    &amp;quot;TraceId&amp;quot;: &amp;quot;FGTRR55322843442124780&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSources&amp;quot;: [&amp;quot;All&amp;quot;],&lt;br /&gt;
    &amp;quot;GuestCheckOut&amp;quot; : true,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;EXMPLSHOP-PM-002/TR001&amp;quot;,&lt;br /&gt;
            &amp;quot;Payee&amp;quot;: &amp;quot;[[MERCHANTS_BARION_EMAIL]]&amp;quot;,&lt;br /&gt;
            &amp;quot;Total&amp;quot;: 25.2,&lt;br /&gt;
            &amp;quot;Comment&amp;quot;: &amp;quot;Subscription fee for the second month&amp;quot;,&lt;br /&gt;
            &amp;quot;Items&amp;quot;: [&lt;br /&gt;
                {&lt;br /&gt;
                    &amp;quot;Name&amp;quot;: &amp;quot;Website subscription&amp;quot;,&lt;br /&gt;
                    &amp;quot;Description&amp;quot;: &amp;quot;Website subscription for one month&amp;quot;,&lt;br /&gt;
                    &amp;quot;Quantity&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;Unit&amp;quot;: &amp;quot;month&amp;quot;,&lt;br /&gt;
                    &amp;quot;UnitPrice&amp;quot;: 25.2,&lt;br /&gt;
                    &amp;quot;ItemTotal&amp;quot;: 25.2,&lt;br /&gt;
                    &amp;quot;SKU&amp;quot;: &amp;quot;EXMPLSHOP/SKU/PHC-02&amp;quot;&lt;br /&gt;
                }&lt;br /&gt;
            ]&lt;br /&gt;
        }&lt;br /&gt;
    ]&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== Example response to this request ====&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=json line highlight=&amp;quot;4,8,11&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;PaymentId&amp;quot;: &amp;quot;fb582913dc2feb11a49f309c23734b1c&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;EXMPLSHOP-PM-002&amp;quot;,&lt;br /&gt;
    &amp;quot;Status&amp;quot;: &amp;quot;Succeeded&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        ...&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;RecurrenceResult&amp;quot;: &amp;quot;Successful&amp;quot;,&lt;br /&gt;
    &amp;quot;ThreeDSAuthClientData&amp;quot;: null,&lt;br /&gt;
     ...&lt;br /&gt;
    &amp;quot;TraceId&amp;quot;: &amp;quot;FGTRR55322843442124780&amp;quot;,&lt;br /&gt;
    &amp;quot;Errors&amp;quot;: []&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The structure of the response is the same as the normal &amp;lt;tt&amp;gt;/Payment/Start&amp;lt;/tt&amp;gt; response just the statuses will be different. In this case&lt;br /&gt;
* the payment level &amp;lt;code&amp;gt;Status&amp;lt;/code&amp;gt; will be &#039;&#039;&#039;Succeeded&#039;&#039;&#039; instead of &#039;&#039;&#039;Prepared&#039;&#039;&#039;&lt;br /&gt;
* the &amp;lt;code&amp;gt;RecurrenceResult&amp;lt;/code&amp;gt; will be &#039;&#039;&#039;Successful&#039;&#039;&#039; (or &#039;&#039;&#039;Failed&#039;&#039;&#039;) instead of &#039;&#039;&#039;None&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
The value of the &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; will be the same as in the request.&lt;br /&gt;
&lt;br /&gt;
== Subsequent payments in case of Merchant Initiated Payment scenario ==&lt;br /&gt;
&lt;br /&gt;
In this scenario there are no restrictions.&lt;br /&gt;
&lt;br /&gt;
==== Example payment/start of a subsequent Merchant Initiated Payment ====&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=json line highlight=&amp;quot;5-8&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;POSKey&amp;quot;: &amp;quot;[[SECRET_POS_KEY]]&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;EXMPLSHOP-PM-002&amp;quot;,&lt;br /&gt;
    &amp;quot;InitiateRecurrence&amp;quot;: false,&lt;br /&gt;
    &amp;quot;RecurrenceId&amp;quot;: &amp;quot;SHOP-XMLP-TOKEN-ABC-123&amp;quot;,&lt;br /&gt;
    &amp;quot;RecurrenceType&amp;quot;: &amp;quot;MerchantInitiatedPayment&amp;quot;,&lt;br /&gt;
    &amp;quot;TraceId&amp;quot;: &amp;quot;KBYRR55322844552124780&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSources&amp;quot;: [&amp;quot;All&amp;quot;],&lt;br /&gt;
    &amp;quot;GuestCheckOut&amp;quot; : true,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;EXMPLSHOP-PM-002/TR001&amp;quot;,&lt;br /&gt;
            &amp;quot;Payee&amp;quot;: &amp;quot;[[MERCHANTS_BARION_EMAIL]]&amp;quot;,&lt;br /&gt;
            &amp;quot;Total&amp;quot;: 75,&lt;br /&gt;
            &amp;quot;Comment&amp;quot;: &amp;quot;Usage fee for 2020/12&amp;quot;,&lt;br /&gt;
            &amp;quot;Items&amp;quot;: [&lt;br /&gt;
                {&lt;br /&gt;
                    &amp;quot;Name&amp;quot;: &amp;quot;Phone bill&amp;quot;,&lt;br /&gt;
                    &amp;quot;Description&amp;quot;: &amp;quot;Usage fee for 2020/12&amp;quot;,&lt;br /&gt;
                    &amp;quot;Quantity&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;Unit&amp;quot;: &amp;quot;month&amp;quot;,&lt;br /&gt;
                    &amp;quot;UnitPrice&amp;quot;: 75,&lt;br /&gt;
                    &amp;quot;ItemTotal&amp;quot;: 75,&lt;br /&gt;
                    &amp;quot;SKU&amp;quot;: &amp;quot;EXMPLSHOP/SKU/PHC-02&amp;quot;&lt;br /&gt;
                }&lt;br /&gt;
            ]&lt;br /&gt;
        }&lt;br /&gt;
    ]&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
==== Example response to this request ====&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=json line highlight=&amp;quot;4,8,11&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;PaymentId&amp;quot;: &amp;quot;fb582913dc2feb11a49f309c23734b1c&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;EXMPLSHOP-PM-002&amp;quot;,&lt;br /&gt;
    &amp;quot;Status&amp;quot;: &amp;quot;Succeeded&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        ...&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;RecurrenceResult&amp;quot;: &amp;quot;Successful&amp;quot;,&lt;br /&gt;
    &amp;quot;ThreeDSAuthClientData&amp;quot;: null,&lt;br /&gt;
     ...&lt;br /&gt;
    &amp;quot;TraceId&amp;quot;: &amp;quot;KBYRR55322844552124780&amp;quot;,&lt;br /&gt;
    &amp;quot;Errors&amp;quot;: []&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
The structure of the response is the same as the normal &amp;lt;tt&amp;gt;/Payment/Start&amp;lt;/tt&amp;gt; response just the statuses will be different. In this case&lt;br /&gt;
* the payment level &amp;lt;code&amp;gt;Status&amp;lt;/code&amp;gt; will be &#039;&#039;&#039;Succeeded&#039;&#039;&#039; instead of &#039;&#039;&#039;Prepared&#039;&#039;&#039;&lt;br /&gt;
* the &amp;lt;code&amp;gt;RecurrenceResult&amp;lt;/code&amp;gt; will be &#039;&#039;&#039;Successful&#039;&#039;&#039; (or &#039;&#039;&#039;Failed&#039;&#039;&#039;) instead of &#039;&#039;&#039;None&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
The value of the &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; will be the same as in the request.&lt;br /&gt;
&lt;br /&gt;
== Subsequent payments in case of OneClick Payment scenario ==&lt;br /&gt;
&lt;br /&gt;
In this scenario, the merchant has to prepare to perform the [[#Off-site 3DS v2 authentication|off-site 3DS v2 authentication]] of the payer. 3DS authentication is not required in the following cases:&lt;br /&gt;
* the token (&amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt;) was requested before 3DS came into effect,&lt;br /&gt;
* the original payment was not initialized by bank card,&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
The &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; is not used in this scenario since the payer is present during the transaction. &lt;br /&gt;
&lt;br /&gt;
==== Example payment/start of a subsequent OneClick Payment ====&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=json line highlight=&amp;quot;5-7&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;POSKey&amp;quot;: &amp;quot;[[SECRET_POS_KEY]]&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentType&amp;quot;: &amp;quot;Immediate&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;EXMPLSHOP-PM-002&amp;quot;,&lt;br /&gt;
    &amp;quot;InitiateRecurrence&amp;quot;: false,&lt;br /&gt;
    &amp;quot;RecurrenceId&amp;quot;: &amp;quot;SHOP-XMLP-TOKEN-ABC-123&amp;quot;,&lt;br /&gt;
    &amp;quot;RecurrenceType&amp;quot;: &amp;quot;OneClickPayment&amp;quot;,&lt;br /&gt;
    &amp;quot;FundingSources&amp;quot;: [&amp;quot;All&amp;quot;],&lt;br /&gt;
    &amp;quot;GuestCheckOut&amp;quot; : true,&lt;br /&gt;
    &amp;quot;Currency&amp;quot;: &amp;quot;EUR&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        {&lt;br /&gt;
            &amp;quot;POSTransactionId&amp;quot;: &amp;quot;EXMPLSHOP-PM-002/TR001&amp;quot;,&lt;br /&gt;
            &amp;quot;Payee&amp;quot;: &amp;quot;[[MERCHANTS_BARION_EMAIL]]&amp;quot;,&lt;br /&gt;
            &amp;quot;Total&amp;quot;: 17,&lt;br /&gt;
            &amp;quot;Comment&amp;quot;: &amp;quot;Book: How to shop online&amp;quot;,&lt;br /&gt;
            &amp;quot;Items&amp;quot;: [&lt;br /&gt;
                {&lt;br /&gt;
                    &amp;quot;Name&amp;quot;: &amp;quot;How to shop online&amp;quot;,&lt;br /&gt;
                    &amp;quot;Description&amp;quot;: &amp;quot;Book about shopping online&amp;quot;,&lt;br /&gt;
                    &amp;quot;Quantity&amp;quot;: 1,&lt;br /&gt;
                    &amp;quot;Unit&amp;quot;: &amp;quot;piece&amp;quot;,&lt;br /&gt;
                    &amp;quot;UnitPrice&amp;quot;: 17,&lt;br /&gt;
                    &amp;quot;ItemTotal&amp;quot;: 17,&lt;br /&gt;
                    &amp;quot;SKU&amp;quot;: &amp;quot;EXMPLSHOP/SKU/PHC-02&amp;quot;&lt;br /&gt;
                }&lt;br /&gt;
            ]&lt;br /&gt;
        }&lt;br /&gt;
    ]&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
==== Example response to this request ====&lt;br /&gt;
&lt;br /&gt;
In this scenario, the response contains the &amp;lt;code&amp;gt;ThreeDSAuthClientData&amp;lt;/code&amp;gt; property that is used to perform an [[#Off-site 3DS v2 authentication|off-site 3DS v2 authentication]].&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=json line highlight=&amp;quot;4,8-9&amp;quot;&amp;gt;&lt;br /&gt;
{&lt;br /&gt;
    &amp;quot;PaymentId&amp;quot;: &amp;quot;fb582913dc2feb11a49f309c23734b1c&amp;quot;,&lt;br /&gt;
    &amp;quot;PaymentRequestId&amp;quot;: &amp;quot;EXMPLSHOP-PM-002&amp;quot;,&lt;br /&gt;
    &amp;quot;Status&amp;quot;: &amp;quot;Succeeded&amp;quot;,&lt;br /&gt;
    &amp;quot;Transactions&amp;quot;: [&lt;br /&gt;
        ...&lt;br /&gt;
    ],&lt;br /&gt;
    &amp;quot;RecurrenceResult&amp;quot;: &amp;quot;ThreeDSAuthenticationRequired&amp;quot;,&lt;br /&gt;
    &amp;quot;ThreeDSAuthClientData&amp;quot;: &amp;quot;ewoJIkNhcmRQdWJs...WZXJzaW9uIjogIjIuMS4wIgp9Cg==&amp;quot;,&lt;br /&gt;
     ...&lt;br /&gt;
    &amp;quot;Errors&amp;quot;: []&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Possible error responses for the subsequent payment requests ==&lt;br /&gt;
&lt;br /&gt;
{| class=&amp;quot;wikitable api-table&amp;quot;&lt;br /&gt;
! Error code || Description&lt;br /&gt;
|-&lt;br /&gt;
| InvalidRecurrenceId|| The token specified in the &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; is invalid. Check if the token registration was successful.&lt;br /&gt;
|-&lt;br /&gt;
| RecurringPaymentDenied|| Something happened to the user since the token registration, either deleted, suspended, or blocked. The payment s not allowed in these cases.&lt;br /&gt;
|-&lt;br /&gt;
| InsufficientFunds|| If the original payment was with an e-money wallet and the customer doesn&#039;t have enough money to fulfill this charge this error happens.&lt;br /&gt;
|-&lt;br /&gt;
| OriginalPaymentWasntSuccessful || This means that the token belongs to an originally unsuccessful payment so this token can not be used anymore. This could only happen if the original payment was financed with a credit card.&lt;br /&gt;
|-&lt;br /&gt;
|InvalidCurrency || If the original payment was paid with e-money and the current token payment is in a currency that the wallet does not have an account in this error happens.&lt;br /&gt;
|-&lt;br /&gt;
|CardExpired || The card that was used to fulfill the initial payment is no longer valid. The &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; has to be re-initialized.&lt;br /&gt;
|-&lt;br /&gt;
|TopUpFailed || The attempt to charge the card that was use to fulfill the initial payment was unsuccessful. Often accompanied by other more specific errors.&lt;br /&gt;
|-&lt;br /&gt;
|ThreeDsNotEnabled || The card issuer rejected the card due to lack of Strong Customer Authentication. Check whether the &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; is specified correctly (in case the scenario requires it).&lt;br /&gt;
|-&lt;br /&gt;
|InvalidUser || The payee defined in the transaction is not a valid Barion wallet. Either does not exist or not fully activated.&lt;br /&gt;
|-&lt;br /&gt;
|UserCantMakeOutgoingTransaction || The payee specified in the transaction is not allowed to make payeetransactions since the wallet is suspended or does not exist.&lt;br /&gt;
|-&lt;br /&gt;
|CardError || An error happened in the 3DSecure authentication system or the bank system when trying to process the card that has been used to complete the initial payment. This can mean a few things, from security settings to active limits on the card. The possible reasons should be discussed with the customer.&lt;br /&gt;
|-&lt;br /&gt;
|PingFailed || The bank system (or other third party) did not respond to the request, so the Barion API cancelled it.&lt;br /&gt;
|-&lt;br /&gt;
|&#039;&#039;&#039;TooManyUnsuccessfulRecurringPaymentAttempts&#039;&#039;&#039;&lt;br /&gt;
|The TooManyUnsuccessfulRecurringPaymentAttempts error occurs when a recurring payment exceeds the maximum allowed number of unsuccessful attempts, which is 5. The recurrence is temporarily blocked to prevent further payment attempts, and the block remains in effect until the next day.&lt;br /&gt;
|-&lt;br /&gt;
|InvalidTraceId&lt;br /&gt;
|Invalid TraceId. Use the [[Token payment 3D Secure#TraceId|TraceId]] received after successful token payment initialization!&lt;br /&gt;
|}&lt;br /&gt;
&lt;br /&gt;
This is the request-response diagram of the subsequent payments:&lt;br /&gt;
&lt;br /&gt;
[[File:Token_payment_2.png]]&lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039;Important:&#039;&#039;&#039; when requesting Transaction Risk Analysis (TRA) during a subsequent payment, and all conditions have been met, challenge is not shown to the user.&lt;br /&gt;
&lt;br /&gt;
== RecurrenceResult: ThreeDSAuthenticationRequired ==&lt;br /&gt;
&lt;br /&gt;
In response to a subsequent payment, this RecurrenceResult can be received. This means that the payment can not be processed due to the lack of 3DS v2 information. &lt;br /&gt;
&lt;br /&gt;
This can happen if the initial payment was successfully authenticated via 3DS v2 but the subsequent payment does not refer to the original authentication with the &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
To fix this, request and store the &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; of the initial payment and then specify it in the subsequent [[Payment-Start-v2]].&lt;br /&gt;
&lt;br /&gt;
To learn the &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; of a previous payment just simply request the payment information via the [[Payment-PaymentState-v4|/v4/Payment/&amp;lt;PaymentId&amp;gt;/PaymentState]] endpoint.&lt;br /&gt;
&lt;br /&gt;
= Changing funding source or token scenarios =&lt;br /&gt;
&lt;br /&gt;
==Changing the funding source==&lt;br /&gt;
&lt;br /&gt;
This could happen if the funding source becomes invalid for some reason (card gets deleted or expires) or the merchant decides to use that token for another payment. In this case, the merchant has to register the &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; again. &lt;br /&gt;
To do this a new payment must be started and in the [[Payment-Start-v2|Payment/Start]] request the following setup should be specified:&lt;br /&gt;
* the &amp;lt;code&amp;gt;InitiateRecurrence&amp;lt;/code&amp;gt; field has to be set to &amp;lt;code&amp;gt;true&amp;lt;/code&amp;gt; &lt;br /&gt;
* the &amp;lt;code&amp;gt;RecurrenceId&amp;lt;/code&amp;gt; has to be specified.&lt;br /&gt;
* and the &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; should not be specified.&lt;br /&gt;
For recurring payments it is recommended to set the amount of this new payment request so that on subsequent payments the amount is equal or lesser, as the banks may check for this. &lt;br /&gt;
&lt;br /&gt;
This means that when a merchant notices that a funding source has expired, the best practice is to notify the customer on the start of the next subscription period, and charge the whole subscription fee on the new funding source.&lt;br /&gt;
&lt;br /&gt;
[[File:Funding-source-change.png|1500px]]&lt;br /&gt;
&lt;br /&gt;
Since the &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; is bound to the payer and the process if the funding source changes new &amp;lt;code&amp;gt;TraceId&amp;lt;/code&amp;gt; will be generated. This new ID must be saved to this payment and must be used from this moment on for subsequent payments.&lt;br /&gt;
&lt;br /&gt;
==Changing the token payment scenario with an existing token==&lt;br /&gt;
&lt;br /&gt;
This scenario is useful when a merchant wants to create a &#039;&#039;&#039;new token scenario&#039;&#039;&#039; for an existing, valid token (RecurrenceID) that has already been registered by the payer.&lt;br /&gt;
&lt;br /&gt;
A new token scenario may be required in situations such as the following:&lt;br /&gt;
&lt;br /&gt;
*&#039;&#039;&#039;Changing the recurring payment schedule&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
:The payer has already subscribed to a service using a recurring payment token. Later, they subscribe to another service that has a different billing schedule. Since the original `RecurringFrequency` no longer applies, the merchant must obtain a new `TraceId` for the new recurring payment scenario.&lt;br /&gt;
&lt;br /&gt;
*&#039;&#039;&#039;Converting a one-click payment token into a recurring payment token&#039;&#039;&#039;&lt;br /&gt;
&lt;br /&gt;
:The payer previously made a purchase and registered a token for one-click payments. Later, the payer subscribes to a recurring service from the same merchant. Because recurring payments represent a different token scenario, the merchant must obtain a new `TraceId`. This can be done without redirecting the payer to Barion by using the existing `RecurrenceId` and performing 3D Secure (3DS) authentication directly on the merchant&#039;s website.&lt;br /&gt;
&lt;br /&gt;
===Creating a new token scenario===&lt;br /&gt;
&lt;br /&gt;
To create a new token scenario, the merchant must start a new payment. In the `Payment/Start` request, the following fields should be set:&lt;br /&gt;
&lt;br /&gt;
* `InitiateRecurrence` = `false`&lt;br /&gt;
* Specify the existing `RecurrenceId`.&lt;br /&gt;
* Do &#039;&#039;&#039;not&#039;&#039;&#039; specify a `TraceId`.&lt;br /&gt;
&lt;br /&gt;
After the payment is started, the payer must complete a 3DS authentication on the merchant&#039;s website without redirecting the payer to Barion (see `barion.offsitegw.js` in the  next chapter). Once the authentication is successful, a new `TraceId` is generated for the new token scenario.&lt;br /&gt;
&lt;br /&gt;
===Result===&lt;br /&gt;
&lt;br /&gt;
A single `RecurrenceId` can be associated with multiple `TraceId` values, where each `TraceId` represents a different payment scenario (for example recurring payments with different billing schedules).&lt;br /&gt;
&lt;br /&gt;
This allows merchants to organize and distinguish token usage by payment scenario instead of treating every subsequent payment as part of the same recurring payment flow.&lt;br /&gt;
&lt;br /&gt;
=== [[File:Mutiple-traceid.png|1500px]] Multiple recurrence identifiers ===&lt;br /&gt;
A customer is identified by the email address of the Barion account that was used for the token registration. The same customer can register more than one funding source at the same shop, for example several bank cards, and every registered card has its own `RecurrenceId` token. All of these tokens belong to the same email address, so a merchant can keep several tokens for one customer profile at the same time.&lt;br /&gt;
&lt;br /&gt;
This makes it possible to let the customer choose which stored card to pay with. The merchant stores the `RecurrenceId` of every registered card together with the `FundingInformation` returned by Barion, displays the stored cards to the customer based on that information, and starts the subsequent payment with the `RecurrenceId` that belongs to the card the customer selected.&lt;br /&gt;
&lt;br /&gt;
Each `RecurrenceId` can be associated with several `TraceId` values, one for every token payment scenario the token is used in. The trace IDs are independent of each other and can be used in parallel, as long as each of them is used for the scenario it was generated for.&lt;br /&gt;
&lt;br /&gt;
For this reason every `TraceId` must be stored together with the `RecurrenceId` and the token scenario it belongs to, and every subsequent payment must refer to the trace ID that matches the scenario of that payment.&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;
The identifiers form the following hierarchy:&lt;br /&gt;
&lt;br /&gt;
[[File:Identifiers-hierarchy.png|frameless]]&lt;br /&gt;
&lt;br /&gt;
= Off-site 3DS v2 authentication =&lt;br /&gt;
&lt;br /&gt;
In certain scenarios, the payer has to be authenticated to lower the risk of the card transaction. This can be either performed &lt;br /&gt;
* on the Barion Smart Gateway (on-site) by redirecting the customer to Barion &lt;br /&gt;
* or on the merchant&#039;s website (off-site) by integrating the Barion Off-site client library.&lt;br /&gt;
&lt;br /&gt;
This section describes how to integrate the Barion off-site authentication library into the merchant&#039;s site.&lt;br /&gt;
&lt;br /&gt;
== Step 1 : Initialize the off-site authentication library  ==&lt;br /&gt;
You have to include the following css and javascript files in the code of your site. &lt;br /&gt;
&amp;lt;source lang=html&amp;gt;&lt;br /&gt;
&amp;lt;link href=&amp;quot;https://secure.barion.com/static/barion.offsitegw.min.css&amp;quot; rel=&amp;quot;stylesheet&amp;quot;&amp;gt;&lt;br /&gt;
&amp;lt;script src=&amp;quot;https://secure.barion.com/static/barion.offsitegw.min.js&amp;quot;&amp;gt;&amp;lt;/script&amp;gt;&lt;br /&gt;
&amp;lt;/source &amp;gt;&lt;br /&gt;
These files include all the necessary javascript code and styling to handle the 3DS authentication and display the challenge if necessary.&lt;br /&gt;
&lt;br /&gt;
Then you have to initialize the Barion javascript client. To do that, you have to define a configuration object that specifies your functions that handle the off-site authentication events. &lt;br /&gt;
&lt;br /&gt;
&#039;&#039;&#039; Authentication events&#039;&#039;&#039;&lt;br /&gt;
* &amp;lt;code&amp;gt;onAuthenticationSucceeded&amp;lt;/code&amp;gt;: the 3DS v2 authentication successfully completed&lt;br /&gt;
* &amp;lt;code&amp;gt;onAuthenticationFailed&amp;lt;/code&amp;gt;:  the 3DS v2 authentication failed&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=javascript&amp;gt;&lt;br /&gt;
const configuration = {&lt;br /&gt;
    onAuthenticationSucceeded: function () {&lt;br /&gt;
        // handle successful authentication by calling the Barion API via merchant&#039;s backend&lt;br /&gt;
        // Call the v2/payment/complete endpoint&lt;br /&gt;
    },&lt;br /&gt;
    onAuthenticationFailed: function () {&lt;br /&gt;
        // Handle unsuccessful authentication result, no charge was made.&lt;br /&gt;
        // The payment might be still valid only the authentication failed&lt;br /&gt;
    }&lt;br /&gt;
}&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Then you have to pass this config object to the library.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=javascript&amp;gt;&lt;br /&gt;
const gw = new Barion.OffsiteGw(configuration);&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
Once the DOM is loaded you have to initialize the library:&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=javascript&amp;gt;&lt;br /&gt;
document.addEventListener(&amp;quot;DOMContentLoaded&amp;quot;, function () {&lt;br /&gt;
    // Initiate the Barion Offiste GW library&lt;br /&gt;
    gw.init();&lt;br /&gt;
});&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
== Step 2: Start the authentication process ==&lt;br /&gt;
Once the &amp;lt;code&amp;gt;ThreeDSAuthClientData&amp;lt;/code&amp;gt; is acquired from the payment/start you can start the authentication process by calling the &amp;lt;code&amp;gt;authenticate()&amp;lt;/code&amp;gt; method of the library.&lt;br /&gt;
&lt;br /&gt;
&amp;lt;source lang=javascript&amp;gt;&lt;br /&gt;
gw.authenticate(threeDsClientData);&lt;br /&gt;
&amp;lt;/source&amp;gt;&lt;br /&gt;
&lt;br /&gt;
This will start the authentication process and present the challenge if needed. Visually this will create a modal window over the merchant&#039;s site and show the payer every necessary information.&lt;br /&gt;
Once the authentication process finished (either with or without a challenge) the appropriate event will be fired.&lt;br /&gt;
&lt;br /&gt;
The sizing of the modal window is based on the viewport configured on the merchant&#039;s site. We highly recommend inserting and extending the following [https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag viewport meta tag]: &amp;lt;code&amp;gt;&amp;lt;meta name=&amp;quot;viewport&amp;quot; content=&amp;quot;width=device-width, initial-scale=1&amp;quot; /&amp;gt;&amp;lt;/code&amp;gt;.&lt;br /&gt;
&lt;br /&gt;
== Step 3: Completing the payment ==&lt;br /&gt;
&lt;br /&gt;
In case of successful authentication, you have to call our [[Payment-Complete-v3|/Payment/Complete]] endpoint, where the actual charge will happen.&lt;br /&gt;
&lt;br /&gt;
=== Possible error responses for the subsequent payment requests ===&lt;br /&gt;
[https://docs.barion.com/Token_payment_3D_Secure#Possible_error_responses_for_the_subsequent_payment_requests Possible error responses for the subsequent payment requests]&lt;br /&gt;
&lt;br /&gt;
== Suggested implementation flow for off-site authentication ==&lt;br /&gt;
&lt;br /&gt;
Ideally, an off-site authentication should be part of a client-side experience without any postbacks or page reloads. This is our recommendation to achieve this:&lt;br /&gt;
&lt;br /&gt;
# After the customer clicks on the &amp;quot;Pay&amp;quot; button make an AJAX call from your client-side code to your back-end. &lt;br /&gt;
# Have your backend make a request to our payment/start endpoint (with the appropriate settings for the desired token scenario)&lt;br /&gt;
# Have your backend process the response and pass the value of the &amp;lt;code&amp;gt;ThreeDSAuthClientData&amp;lt;/code&amp;gt; property to your client-side code.&lt;br /&gt;
# Use the Barion off-site library to perform the authentication&lt;br /&gt;
# Once the authentication succeeds send another AJAX request from your client-side code to your back-end.&lt;br /&gt;
# Have your back-end code call our [[Payment-Complete-v3|/Payment/Complete]]&lt;br /&gt;
# Have your backend process the response and pass the result to your client-side code.&lt;br /&gt;
# Display the result for the customer&lt;br /&gt;
&lt;br /&gt;
= Testing the integration =&lt;br /&gt;
&lt;br /&gt;
3D Secure has no environment for end-to-end testing, therefore merchants have to split their testings into two parts: Testing the payment flow with and without challenge. Getting a challenge is only possible with real-life cards, merchants have to use their own (there will be no real charging at the end on the Sandbox of the Payment Gateway, but using a real card will result initiating a real 3DS authentication).&lt;br /&gt;
&lt;br /&gt;
== Testing the whole payment flow, without challenge ==&lt;br /&gt;
&lt;br /&gt;
Use the [[https://docs.barion.com/Sandbox#Test_cards Barion test cards]], they will always get a &amp;quot;frictionless&amp;quot; flow, where the 3DS process is presented on the UI, but you will never see a challenge screen. &lt;br /&gt;
&lt;br /&gt;
This is good for testing your integration itself because it will lead to a successful charge, and you will get a TraceId as well.&lt;br /&gt;
&lt;br /&gt;
== Testing the challenge itself ==&lt;br /&gt;
&lt;br /&gt;
Use your own card, and let the card issuer decide whether your payment will get a challenge or not during the 3DS authentication procedure. Your payment will fail at the end, and you won&#039;t get the TraceId. &lt;br /&gt;
&lt;br /&gt;
This is good to test, how the challenge screens look like in your shop - especially when you integrated OneClick payment directly to your shop. You might also check how your customers see your checkout flow on popular devices.&lt;/div&gt;</summary>
		<author><name>Vargaj@barion.dev</name></author>
	</entry>
</feed>