Barion Shop Authentication

From Barion Documentation
Revision as of 15:45, 20 October 2026 by [email protected] (talk | contribs)
Jump to navigation Jump to search

What is shop authentication?

The API endpoints related to handling a shop's payment flow are accessible using the shop's own unique API key, known as POS key.

For a full list of such endpoints see List of Barion API endpoints.

Optionally, the shop can also use an HMAC key to sign its API requests and to verify the messages Barion sends to it. See Message signature (HMAC).

Using POS keys

To use an endpoint which requires shop-level authentication, pass your Barion shop's POS key as the x-pos-key header parameter.

NOTE
GET API endpoints below v4 also accept the PosKey property as a query parameter.

Errors

An invalid key generates an AuthenticationFailed error.

Managing POS keys

A POS key is automatically generated for your shop when you create it, and cannot be changed later. To obtain it, either

  • get the key from the confirmation e-mail that was sent to you when you opened the shop, or
  • go to the shop's detail page on the Barion secure site and use the Secret key value (Shops -> Actions -> Details)
NOTE
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:

Message signature (HMAC)

A shop can have an HMAC key in addition to its POS key. While the shop has an active HMAC key:

  • every API request authenticated with the shop's POS key must be signed with the HMAC key, otherwise Barion rejects it,
  • Barion signs its responses to these requests, and
  • Barion signs the payment IPN (callback) messages it sends to the shop.

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.

The signature is an HMAC-SHA512 computed with the shop's HMAC key. It is sent in HTTP headers, so the request and response bodies do not change.

IMPORTANT
Activating a key takes effect immediately: 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 before you activate the key.

Managing HMAC keys

HMAC keys are managed on the Barion secure site, on the shop's security page (Shops -> Actions -> Settings -> Security -> Manage).

  • A shop can have at most 2 HMAC keys. To generate a third one, delete one of the two first.
  • A new key is created inactive. Mark it as Active when your server is ready.
  • At most one key is active at a time. If no key is active, nothing is signed and no signature is checked.
  • The active key cannot be deleted. Deactivate it, or activate the other key, first.
  • The key is shown and copied as a base64 string. Decode it from base64 and use the resulting 64 bytes as the HMAC key.
NOTE
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.

Signature headers

Every signed request and response carries these three headers:

Header Content
x-timestamp The time of signing as a Unix timestamp in seconds (UTC), e.g. 1760968800.
x-nonce A GUID, e.g. 3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84. In a request it must be new for every request. In a response it is the nonce of the request being answered.
x-signature-sha512 The HMAC-SHA512 of the signed text (see below), base64-encoded.

The signed text

The signature is computed over a text made of the following parts, joined with a single line feed character (\n, LF, no carriage return). The text is UTF-8 encoded before signing.

Requests (your API requests and Barion's IPN)

{x-timestamp}\n{x-nonce}\n{HTTP method}\n{path and query}\n{body}
  • HTTP method: in upper case, e.g. POST or GET.
  • path and query: the path and the query string of the URL as it appears on the request line, e.g. /v2/Payment/Start or /v4/Payment/GetPaymentState?PaymentId=.... The scheme, the host and the port are not part of it.
  • body: the exact request body, byte for byte as it is sent. For a request without a body (e.g. GET) it is an empty string, so the text ends with the line feed after the path.

Responses (Barion's answers to your signed requests)

{x-timestamp}\n{x-nonce}\n{HTTP status code}\n{body}
  • x-nonce: the nonce of your request that the response answers. It is echoed back in the response's x-nonce header, and binds the response to your request.
  • HTTP status code: as a number, e.g. 200.
  • body: the exact response body as received.

Responses are signed only when the request was signed correctly.

Signing your API requests

  1. Generate a new GUID for x-nonce and take the current Unix time in seconds for x-timestamp.
  2. Build the signed text from the timestamp, the nonce, the method, the path and query, and the exact body you are going to send.
  3. Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.
  4. Send the request with the x-pos-key, x-timestamp, x-nonce and x-signature-sha512 headers.

Barion checks that:

  • the timestamp is within 5 minutes of the server time, in either direction,
  • the nonce has not been used by the shop before (so a captured request cannot be replayed),
  • the signature matches the request signed with the active key.

Verifying Barion's messages

For a response to your request, and for a payment IPN message:

  1. Read the x-timestamp, x-nonce and x-signature-sha512 headers.
  2. Build the signed text: for a response with the response's status code and body, for an IPN with POST, the path and query of your callback URL as it was called (including the paymentId query parameter) and the request body.
  3. Compute the HMAC-SHA512 with your active key and compare it with x-signature-sha512. Use a constant-time comparison.
  4. 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.


Example

Signing a request in C#:

using System;
using System.Security.Cryptography;
using System.Text;

static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body)
{
    string text = string.Join("\n", timestamp, nonce, method.ToUpperInvariant(), pathAndQuery, body ?? "");

    using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey)))
    {
        return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(text)));
    }
}

string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
string nonce = Guid.NewGuid().ToString();
string body = "{\"PaymentRequestId\":\"...\"}";
string signature = Sign(hmacKey, timestamp, nonce, "POST", "/v2/Payment/Start", body);

// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature}

Rotating the key

  1. Generate a second key on the security page. The current key keeps working.
  2. Prepare your server to sign with the new key and to verify with it.
  3. Mark the new key as Active. 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.
  4. Once your server no longer uses the old key, delete the old key.

Turning signing off

Untick Active 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's IPN messages and responses too.

Errors

If the shop has an active HMAC key and the signature check fails, the request is rejected with HTTP status 401 and one of these errors:

Error code Meaning
MissingSignature One or more of the x-timestamp, x-nonce and x-signature-sha512 headers is missing.
InvalidNonce x-nonce is not a GUID.
InvalidTimestamp x-timestamp is not a Unix timestamp in seconds, or is more than 5 minutes off the server time.
InvalidSignature The signature does not match the request signed with the shop's active HMAC key.
ReplayedRequest A request with this x-nonce has already been received.