PosKey property as a query parameter.Barion Shop Authentication: Difference between revisions
No edit summary |
No edit summary |
||
| Line 37: | Line 37: | ||
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. | 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. | ||
{{NotificationBox|title=IMPORTANT|text= | {{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 <b>24 hour change period</b>: 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 <b>before</b> you activate the key.|color=#D73E48}} | ||
== Managing HMAC keys == | == Managing HMAC keys == | ||
| Line 76: | Line 76: | ||
* '''HTTP method''': in upper case, e.g. <code>POST</code> or <code>GET</code>. | * '''HTTP method''': in upper case, e.g. <code>POST</code> or <code>GET</code>. | ||
* '''path and query''': the path and the query string of the URL as it appears on the request line, e.g. <code>/v2/ | * '''path and query''': the path and the query string of the URL as it appears on the request line, '''in lower case''', e.g. <code>/v2/payment/start</code> or <code>/v4/payment/getpaymentstate?paymentid=...</code>. 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. <code>GET</code>) it is an empty string, so the text ends with the line feed after the path. | * '''body''': the exact request body, byte for byte as it is sent, and '''not''' 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. <code>GET</code>) it is an empty string, so the text ends with the line feed after the path. | ||
{{NotificationBox|title=NOTE|text=The path and the query string are signed in <b>lower case</b>, 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, <code>%C3</code> becomes <code>%c3</code>) 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}} | |||
=== Responses (Barion's answers to your signed requests) === | === Responses (Barion's answers to your signed requests) === | ||
| Line 94: | Line 96: | ||
# Generate a new GUID for <code>x-nonce</code> and take the current Unix time in seconds for <code>x-timestamp</code>. | # Generate a new GUID for <code>x-nonce</code> and take the current Unix time in seconds for <code>x-timestamp</code>. | ||
# Build the signed text from the timestamp, the nonce, the method, the path and query, and the exact body you are going to send. | # 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. | ||
# Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result. | # Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result. | ||
# Send the request with the <code>x-pos-key</code>, <code>x-timestamp</code>, <code>x-nonce</code> and <code>x-signature-sha512</code> headers. | # Send the request with the <code>x-pos-key</code>, <code>x-timestamp</code>, <code>x-nonce</code> and <code>x-signature-sha512</code> headers. | ||
| Line 107: | Line 109: | ||
For a response to your request, and for a payment IPN message: | For a response to your request, and for a payment IPN message: | ||
# Read the <code>x-timestamp</code>, <code>x-nonce</code> and <code>x-signature-sha512</code> headers. | # Read the <code>x-timestamp</code>, <code>x-nonce</code> and <code>x-signature-sha512</code> headers. | ||
# Build the signed text: for a response with the response's status code and body, for an IPN with <code>POST</code>, the path and query of your callback URL as it was called (including the <code>paymentId</code> query parameter) and the request body. | # Build the signed text: for a response with the response's status code and body, for an IPN with <code>POST</code>, the path and query of your callback URL as it was called (including the <code>paymentId</code> query parameter), in lower case, and the request body. | ||
# Compute the HMAC-SHA512 with your active key and compare it with <code>x-signature-sha512</code>. Use a constant-time comparison. | # Compute the HMAC-SHA512 with your active key and compare it with <code>x-signature-sha512</code>. Use a constant-time comparison. | ||
# 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.<br /> | # 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.<br /> | ||
| Line 121: | Line 123: | ||
static string Sign(string base64HmacKey, string timestamp, string nonce, string method, string pathAndQuery, string body) | 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 ?? ""); | // The path and query are signed in lower case; the body is used as it is. | ||
string text = string.Join("\n", timestamp, nonce, method.ToUpperInvariant(), pathAndQuery.ToLowerInvariant(), body ?? ""); | |||
using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey))) | using (var hmac = new HMACSHA512(Convert.FromBase64String(base64HmacKey))) | ||
| Line 135: | Line 138: | ||
// Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature} | // Send with the headers: x-pos-key, x-timestamp: {timestamp}, x-nonce: {nonce}, x-signature-sha512: {signature} | ||
</pre> | |||
== Test vectors == | |||
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's own code and cross-checked with <code>openssl</code>. | |||
{{NotificationBox|title=NOTE|text=This key is only for these examples. Never use it for a real shop.|color=#038Ed3}} | |||
'''HMAC key''' (base64, to be decoded before use): <code>AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==</code> | |||
It decodes to the 64 bytes <code>0x00, 0x01, 0x02, ... 0x3f</code>, which is <code>000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f</code> in hex. | |||
In the signed texts below, <code>\n</code> 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. | |||
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 <code>0a</code> (a CR LF would be <code>0d0a</code>), and non-ASCII characters are UTF-8 encoded. | |||
=== 1. A request with a JSON body === | |||
<pre> | |||
Method: POST | |||
URL: https://api.barion.com/v2/Payment/Start | |||
x-timestamp: 1760968800 | |||
x-nonce: 3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84 | |||
Body: {"PaymentRequestId":"order-1001","Total":10.50} | |||
</pre> | |||
Signed text (note that the path is in lower case, and the body is used as it is): | |||
<pre> | |||
1760968800\n | |||
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n | |||
POST\n | |||
/v2/payment/start\n | |||
{"PaymentRequestId":"order-1001","Total":10.50} | |||
</pre> | |||
Signed bytes: the UTF-8 encoding of the text above (118 bytes), in hex: | |||
<pre> | |||
313736303936383830300a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a504f53540a2f76322f7061796d656e742f73746172740a7b225061796d656e74526571756573744964223a226f726465722d31303031222c22546f74616c223a31302e35307d | |||
</pre> | |||
and in base64: | |||
<pre> | |||
MTc2MDk2ODgwMAozZjJiNmMxZS04ZDRhLTRiOWUtOWE1MS0wYzdkMmU2ZjFhODQKUE9TVAovdjIvcGF5bWVudC9zdGFydAp7IlBheW1lbnRSZXF1ZXN0SWQiOiJvcmRlci0xMDAxIiwiVG90YWwiOjEwLjUwfQ== | |||
</pre> | |||
x-signature-sha512: | |||
<pre> | |||
AMm7BeXNw0JAs8pxAhemnOQzhlWDz+o/nB85yKPim0DYSCdgpswBQFyQlhFrDwb/MrPFWlcwgDGa+DFGsNJvuQ== | |||
</pre> | |||
=== 2. A GET request without a body === | |||
<pre> | |||
Method: GET | |||
URL: https://api.barion.com/v4/Payment/GetPaymentState?PaymentId=3F2B6C1E-8D4A-4B9E-9A51-0C7D2E6F1A84 | |||
x-timestamp: 1760968800 | |||
x-nonce: 9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f | |||
Body: (none) | |||
</pre> | |||
Signed text. The path and the whole query string are in lower case, including the value of <code>PaymentId</code>. The text ends with the line feed after the query string, because the body is empty: | |||
<pre> | |||
1760968800\n | |||
9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f\n | |||
GET\n | |||
/v4/payment/getpaymentstate?paymentid=3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n | |||
</pre> | |||
Signed bytes: the UTF-8 encoding of the text above (127 bytes), in hex: | |||
<pre> | |||
313736303936383830300a39643661316630652d326237632d346333352d386531392d3561346233633264316530660a4745540a2f76342f7061796d656e742f6765747061796d656e7473746174653f7061796d656e7469643d33663262366331652d386434612d346239652d396135312d3063376432653666316138340a | |||
</pre> | |||
and in base64: | |||
<pre> | |||
MTc2MDk2ODgwMAo5ZDZhMWYwZS0yYjdjLTRjMzUtOGUxOS01YTRiM2MyZDFlMGYKR0VUCi92NC9wYXltZW50L2dldHBheW1lbnRzdGF0ZT9wYXltZW50aWQ9M2YyYjZjMWUtOGQ0YS00YjllLTlhNTEtMGM3ZDJlNmYxYTg0Cg== | |||
</pre> | |||
x-signature-sha512: | |||
<pre> | |||
z8YFYV7YKs4OY4eVfd0BSc1LJMkbmBQRFuNXFO+KiAujB7eR1oHwicRTepgVSDqzHoHow/SDoKTdX2IpNMvB8A== | |||
</pre> | |||
=== 3. A request with a body that is not ASCII === | |||
The body contains the characters <code>é</code>, <code>ő</code> and <code>€</code>. It is signed as UTF-8, that is <code>c3 a9</code>, <code>c5 91</code> and <code>e2 82 ac</code>. | |||
<pre> | |||
Method: POST | |||
URL: https://api.barion.com/v2/Payment/Refund | |||
x-timestamp: 1760968800 | |||
x-nonce: c0ffee00-1234-4abc-8def-0123456789ab | |||
Body: {"Comment":"Pléhő €"} | |||
</pre> | |||
Signed text: | |||
<pre> | |||
1760968800\n | |||
c0ffee00-1234-4abc-8def-0123456789ab\n | |||
POST\n | |||
/v2/payment/refund\n | |||
{"Comment":"Pléhő €"} | |||
</pre> | |||
Signed bytes: the UTF-8 encoding of the text above (97 bytes), in hex: | |||
<pre> | |||
313736303936383830300a63306666656530302d313233342d346162632d386465662d3031323334353637383961620a504f53540a2f76322f7061796d656e742f726566756e640a7b22436f6d6d656e74223a22506cc3a968c59120e282ac227d | |||
</pre> | |||
and in base64: | |||
<pre> | |||
MTc2MDk2ODgwMApjMGZmZWUwMC0xMjM0LTRhYmMtOGRlZi0wMTIzNDU2Nzg5YWIKUE9TVAovdjIvcGF5bWVudC9yZWZ1bmQKeyJDb21tZW50IjoiUGzDqWjFkSDigqwifQ== | |||
</pre> | |||
x-signature-sha512: | |||
<pre> | |||
Hr/GW0mx6tAeDK32aPGAXoM2nk0IluJP+OPmxu3/PVWspiFWDlyAKTfeHn1Qd67KKHxNqa3gORiCvlYGbbnvUA== | |||
</pre> | |||
=== 4. A response === | |||
This is Barion's answer to the request in example 1. It carries the <b>nonce of the request</b> in its <code>x-nonce</code> header, and it has its own timestamp. | |||
<pre> | |||
HTTP status: 200 | |||
x-timestamp: 1760968801 | |||
x-nonce: 3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84 | |||
Body: {"PaymentId":"3f2b6c1e8d4a4b9e9a510c7d2e6f1a84","Status":"Prepared"} | |||
</pre> | |||
Signed text. There is no method and no path in a response, only the status code: | |||
<pre> | |||
1760968801\n | |||
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n | |||
200\n | |||
{"PaymentId":"3f2b6c1e8d4a4b9e9a510c7d2e6f1a84","Status":"Prepared"} | |||
</pre> | |||
Signed bytes: the UTF-8 encoding of the text above (120 bytes), in hex: | |||
<pre> | |||
313736303936383830310a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a3230300a7b225061796d656e744964223a223366326236633165386434613462396539613531306337643265366631613834222c22537461747573223a225072657061726564227d | |||
</pre> | |||
and in base64: | |||
<pre> | |||
MTc2MDk2ODgwMQozZjJiNmMxZS04ZDRhLTRiOWUtOWE1MS0wYzdkMmU2ZjFhODQKMjAwCnsiUGF5bWVudElkIjoiM2YyYjZjMWU4ZDRhNGI5ZTlhNTEwYzdkMmU2ZjFhODQiLCJTdGF0dXMiOiJQcmVwYXJlZCJ9 | |||
</pre> | |||
x-signature-sha512: | |||
<pre> | |||
7C8tktY2Bs91dyw7L/fLKwDQCyriGiVOEvbrurn79sLkT2Q93KDVw7c/LEz4VWIqhZOpzLQbs7a6UCo5BZALyQ== | |||
</pre> | |||
=== 5. A payment IPN message === | |||
Barion calls your callback URL. Sign (or verify) the path and query of the URL <b>as it was called</b>, including the <code>paymentId</code> parameter, and the request body. | |||
<pre> | |||
Method: POST | |||
URL called: https://shop.example/hu/DemoClub/Callback?paymentId=4d924e8da6cbf11199f4001dd8b71d1a | |||
x-timestamp: 1760968802 | |||
x-nonce: 7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d | |||
Body: PaymentId=4d924e8da6cbf11199f4001dd8b71d1a | |||
</pre> | |||
Signed text (the path is in lower case, the scheme and the host are not part of it): | |||
<pre> | |||
1760968802\n | |||
7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d\n | |||
POST\n | |||
/hu/democlub/callback?paymentid=4d924e8da6cbf11199f4001dd8b71d1a\n | |||
PaymentId=4d924e8da6cbf11199f4001dd8b71d1a | |||
</pre> | |||
Signed bytes: the UTF-8 encoding of the text above (160 bytes), in hex: | |||
<pre> | |||
313736303936383830320a37623165346432612d366333662d346138622d396435302d3165326633613462356336640a504f53540a2f68752f64656d6f636c75622f63616c6c6261636b3f7061796d656e7469643d34643932346538646136636266313131393966343030316464386237316431610a5061796d656e7449643d3464393234653864613663626631313139396634303031646438623731643161 | |||
</pre> | |||
and in base64: | |||
<pre> | |||
MTc2MDk2ODgwMgo3YjFlNGQyYS02YzNmLTRhOGItOWQ1MC0xZTJmM2E0YjVjNmQKUE9TVAovaHUvZGVtb2NsdWIvY2FsbGJhY2s/cGF5bWVudGlkPTRkOTI0ZThkYTZjYmYxMTE5OWY0MDAxZGQ4YjcxZDFhClBheW1lbnRJZD00ZDkyNGU4ZGE2Y2JmMTExOTlmNDAwMWRkOGI3MWQxYQ== | |||
</pre> | |||
x-signature-sha512: | |||
<pre> | |||
nwEdCk0K1LeDxLqF+4QnUgtmvl0BQPGqLUl+YawMMoJhcNXnJM9xT8JlmsNyWPwWktbJo2oy+yzx6cUMqUrRiA== | |||
</pre> | |||
=== Checking a value from the command line === | |||
For example, example 1 with <code>openssl</code>: | |||
<pre> | |||
printf '%s\n%s\nPOST\n%s\n%s' 1760968800 3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84 /v2/payment/start '{"PaymentRequestId":"order-1001","Total":10.50}' \ | |||
| openssl dgst -sha512 -mac HMAC -macopt hexkey:000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f -binary \ | |||
| base64 -w0 | |||
</pre> | </pre> | ||
| Line 141: | Line 361: | ||
# Generate a second key on the security page, but do not set it as Active. The current key keeps working. | # Generate a second key on the security page, but do not set it as Active. The current key keeps working. | ||
# 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. | # 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. | ||
# Mark the new key as <i>Active</i> on the security page. From that moment Barion signs with the new key and checks your requests against it. Barion | # Mark the new key as <i>Active</i> 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. | ||
# Switch your server to use the new key for signing requests | # Switch your server to use the new key for signing requests within this change period. | ||
# Once your server | # Once your server uses the new key, we recommend that you <b>delete the old key</b> 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. | ||
== Turning signing off == | == Turning signing off == | ||
Revision as of 09:09, 21 October 2026
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.
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)
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.
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.
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.
POSTorGET. - path and query: the path and the query string of the URL as it appears on the request line, in lower case, e.g.
/v2/payment/startor/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, and not 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.
GET) it is an empty string, so the text ends with the line feed after the path.
%C3 becomes %c3) 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.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-nonceheader, 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
- Generate a new GUID for
x-nonceand take the current Unix time in seconds forx-timestamp. - 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.
- Compute the HMAC-SHA512 of the UTF-8 text with the base64-decoded HMAC key, and base64-encode the result.
- Send the request with the
x-pos-key,x-timestamp,x-nonceandx-signature-sha512headers.
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:
- Read the
x-timestamp,x-nonceandx-signature-sha512headers. - 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 thepaymentIdquery parameter), in lower case, and the request body. - Compute the HMAC-SHA512 with your active key and compare it with
x-signature-sha512. Use a constant-time comparison. - 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)
{
// The path and query are signed in lower case; the body is used as it is.
string text = string.Join("\n", timestamp, nonce, method.ToUpperInvariant(), pathAndQuery.ToLowerInvariant(), 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}
Test vectors
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's own code and cross-checked with openssl.
HMAC key (base64, to be decoded before use): AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==
It decodes to the 64 bytes 0x00, 0x01, 0x02, ... 0x3f, which is 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f in hex.
In the signed texts below, \n 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.
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 0a (a CR LF would be 0d0a), and non-ASCII characters are UTF-8 encoded.
1. A request with a JSON body
Method: POST
URL: https://api.barion.com/v2/Payment/Start
x-timestamp: 1760968800
x-nonce: 3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84
Body: {"PaymentRequestId":"order-1001","Total":10.50}
Signed text (note that the path is in lower case, and the body is used as it is):
1760968800\n
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n
POST\n
/v2/payment/start\n
{"PaymentRequestId":"order-1001","Total":10.50}
Signed bytes: the UTF-8 encoding of the text above (118 bytes), in hex:
313736303936383830300a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a504f53540a2f76322f7061796d656e742f73746172740a7b225061796d656e74526571756573744964223a226f726465722d31303031222c22546f74616c223a31302e35307d
and in base64:
MTc2MDk2ODgwMAozZjJiNmMxZS04ZDRhLTRiOWUtOWE1MS0wYzdkMmU2ZjFhODQKUE9TVAovdjIvcGF5bWVudC9zdGFydAp7IlBheW1lbnRSZXF1ZXN0SWQiOiJvcmRlci0xMDAxIiwiVG90YWwiOjEwLjUwfQ==
x-signature-sha512:
AMm7BeXNw0JAs8pxAhemnOQzhlWDz+o/nB85yKPim0DYSCdgpswBQFyQlhFrDwb/MrPFWlcwgDGa+DFGsNJvuQ==
2. A GET request without a body
Method: GET URL: https://api.barion.com/v4/Payment/GetPaymentState?PaymentId=3F2B6C1E-8D4A-4B9E-9A51-0C7D2E6F1A84 x-timestamp: 1760968800 x-nonce: 9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f Body: (none)
Signed text. The path and the whole query string are in lower case, including the value of PaymentId. The text ends with the line feed after the query string, because the body is empty:
1760968800\n 9d6a1f0e-2b7c-4c35-8e19-5a4b3c2d1e0f\n GET\n /v4/payment/getpaymentstate?paymentid=3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n
Signed bytes: the UTF-8 encoding of the text above (127 bytes), in hex:
313736303936383830300a39643661316630652d326237632d346333352d386531392d3561346233633264316530660a4745540a2f76342f7061796d656e742f6765747061796d656e7473746174653f7061796d656e7469643d33663262366331652d386434612d346239652d396135312d3063376432653666316138340a
and in base64:
MTc2MDk2ODgwMAo5ZDZhMWYwZS0yYjdjLTRjMzUtOGUxOS01YTRiM2MyZDFlMGYKR0VUCi92NC9wYXltZW50L2dldHBheW1lbnRzdGF0ZT9wYXltZW50aWQ9M2YyYjZjMWUtOGQ0YS00YjllLTlhNTEtMGM3ZDJlNmYxYTg0Cg==
x-signature-sha512:
z8YFYV7YKs4OY4eVfd0BSc1LJMkbmBQRFuNXFO+KiAujB7eR1oHwicRTepgVSDqzHoHow/SDoKTdX2IpNMvB8A==
3. A request with a body that is not ASCII
The body contains the characters é, ő and €. It is signed as UTF-8, that is c3 a9, c5 91 and e2 82 ac.
Method: POST
URL: https://api.barion.com/v2/Payment/Refund
x-timestamp: 1760968800
x-nonce: c0ffee00-1234-4abc-8def-0123456789ab
Body: {"Comment":"Pléhő €"}
Signed text:
1760968800\n
c0ffee00-1234-4abc-8def-0123456789ab\n
POST\n
/v2/payment/refund\n
{"Comment":"Pléhő €"}
Signed bytes: the UTF-8 encoding of the text above (97 bytes), in hex:
313736303936383830300a63306666656530302d313233342d346162632d386465662d3031323334353637383961620a504f53540a2f76322f7061796d656e742f726566756e640a7b22436f6d6d656e74223a22506cc3a968c59120e282ac227d
and in base64:
MTc2MDk2ODgwMApjMGZmZWUwMC0xMjM0LTRhYmMtOGRlZi0wMTIzNDU2Nzg5YWIKUE9TVAovdjIvcGF5bWVudC9yZWZ1bmQKeyJDb21tZW50IjoiUGzDqWjFkSDigqwifQ==
x-signature-sha512:
Hr/GW0mx6tAeDK32aPGAXoM2nk0IluJP+OPmxu3/PVWspiFWDlyAKTfeHn1Qd67KKHxNqa3gORiCvlYGbbnvUA==
4. A response
This is Barion's answer to the request in example 1. It carries the nonce of the request in its x-nonce header, and it has its own timestamp.
HTTP status: 200
x-timestamp: 1760968801
x-nonce: 3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84
Body: {"PaymentId":"3f2b6c1e8d4a4b9e9a510c7d2e6f1a84","Status":"Prepared"}
Signed text. There is no method and no path in a response, only the status code:
1760968801\n
3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84\n
200\n
{"PaymentId":"3f2b6c1e8d4a4b9e9a510c7d2e6f1a84","Status":"Prepared"}
Signed bytes: the UTF-8 encoding of the text above (120 bytes), in hex:
313736303936383830310a33663262366331652d386434612d346239652d396135312d3063376432653666316138340a3230300a7b225061796d656e744964223a223366326236633165386434613462396539613531306337643265366631613834222c22537461747573223a225072657061726564227d
and in base64:
MTc2MDk2ODgwMQozZjJiNmMxZS04ZDRhLTRiOWUtOWE1MS0wYzdkMmU2ZjFhODQKMjAwCnsiUGF5bWVudElkIjoiM2YyYjZjMWU4ZDRhNGI5ZTlhNTEwYzdkMmU2ZjFhODQiLCJTdGF0dXMiOiJQcmVwYXJlZCJ9
x-signature-sha512:
7C8tktY2Bs91dyw7L/fLKwDQCyriGiVOEvbrurn79sLkT2Q93KDVw7c/LEz4VWIqhZOpzLQbs7a6UCo5BZALyQ==
5. A payment IPN message
Barion calls your callback URL. Sign (or verify) the path and query of the URL as it was called, including the paymentId parameter, and the request body.
Method: POST URL called: https://shop.example/hu/DemoClub/Callback?paymentId=4d924e8da6cbf11199f4001dd8b71d1a x-timestamp: 1760968802 x-nonce: 7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d Body: PaymentId=4d924e8da6cbf11199f4001dd8b71d1a
Signed text (the path is in lower case, the scheme and the host are not part of it):
1760968802\n 7b1e4d2a-6c3f-4a8b-9d50-1e2f3a4b5c6d\n POST\n /hu/democlub/callback?paymentid=4d924e8da6cbf11199f4001dd8b71d1a\n PaymentId=4d924e8da6cbf11199f4001dd8b71d1a
Signed bytes: the UTF-8 encoding of the text above (160 bytes), in hex:
313736303936383830320a37623165346432612d366333662d346138622d396435302d3165326633613462356336640a504f53540a2f68752f64656d6f636c75622f63616c6c6261636b3f7061796d656e7469643d34643932346538646136636266313131393966343030316464386237316431610a5061796d656e7449643d3464393234653864613663626631313139396634303031646438623731643161
and in base64:
MTc2MDk2ODgwMgo3YjFlNGQyYS02YzNmLTRhOGItOWQ1MC0xZTJmM2E0YjVjNmQKUE9TVAovaHUvZGVtb2NsdWIvY2FsbGJhY2s/cGF5bWVudGlkPTRkOTI0ZThkYTZjYmYxMTE5OWY0MDAxZGQ4YjcxZDFhClBheW1lbnRJZD00ZDkyNGU4ZGE2Y2JmMTExOTlmNDAwMWRkOGI3MWQxYQ==
x-signature-sha512:
nwEdCk0K1LeDxLqF+4QnUgtmvl0BQPGqLUl+YawMMoJhcNXnJM9xT8JlmsNyWPwWktbJo2oy+yzx6cUMqUrRiA==
Checking a value from the command line
For example, example 1 with openssl:
printf '%s\n%s\nPOST\n%s\n%s' 1760968800 3f2b6c1e-8d4a-4b9e-9a51-0c7d2e6f1a84 /v2/payment/start '{"PaymentRequestId":"order-1001","Total":10.50}' \
| openssl dgst -sha512 -mac HMAC -macopt hexkey:000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f -binary \
| base64 -w0
Rotating the key
- Generate a second key on the security page, but do not set it as Active. The current key keeps working.
- 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.
- Mark the new key as Active 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.
- Switch your server to use the new key for signing requests within this change period.
- Once your server uses the new key, we recommend that you delete the old key 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.
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.
|
