Calling the API
Calling the Barion API
The Barion API
Barion offers you a RESTful API service to communicate with your web or mobile merchant services. Learn more about RESTful behavior in the original Wikipedia article.
Protocols and communication
The Barion API communicates via standard HTTP1.1 GET or POST requests. A given API endpoint accepts only either GET or POST requests - there are no universal endpoints available. Each API endpoint reference page lists the path of the API endpoint and the HTTP method it accepts.
If the caller uses an incorrect method, the system responds with a JSON error message.
Example: calling a POST endpoint with a GET request
"Message": "The requested resource does not support HTTP method 'GET'."
The maximum duration for an HTTP request is 30 seconds. After that the server stops the request.
Data and content types
Ensure your API requests meet these requirements:
- JSON strings are UTF-8 encoded.
- The MIME type of the request sent to the API is defined as
- Explicitly specify
Content-lengthin all HTTP request headers.
The data types used in the API communication are the following:
|Standard character string. The Barion API uses UTF-8 encoding.
|32-bit signed integer format
|GUID (Global Unique Identifier)
|A 128-bit long hexadecimal identifier with 32-character string representation, for example 21EC2020-3AEA-4069-A2DD-08002B30309D. Its value is always unique in the Barion system. This is used for example to identify payments. For security and compatibility reasons the GUID is used without hyphens for most of our API.
|Date and time values, represented in a string format of the ISO-8601 standard, for example 2014-12-06T08:35:46Z. All API call responses contain datetimes as strings.
|A time range value represented in a string format of the ISO-8601 standard, like this: 3.14:15:28 (three days, fourteen hours, fifteen minutes, twenty-eight seconds). All API call responses contain datetimes as strings.
Important: Avoid integer or byte evaluation when constructing the request JSON.
|Byte representation of an enumeration value. This is only for internal use in the Barion system, API call responses always contain the string representation.
The base URL for the Barion API depends on the environment you are connecting to.
Base URL for API requests in the Live (production) environment:
To avoid breaking changes, major updates to an API endpoint raise the API version. At the moment, the Barion API offers two different API versions (noted
v2). Some API endpoints are only available in v1 or v2. Check the reference page of a given API endpoint to see available versions.
Note: Though version numbers can be omitted from the endpoint path (such requests always fall back to
v1), we recommend always specifying the API version when sending requests to the Barion API to avoid confusion.
https://api.barion.com/Transaction/List- implicit call to a
v1endpoint (version number is omitted from path)
https://api.barion.com/v1/Transfer/Send- explicit call to a
https://api.barion.com/v2/Payment/Start- explicit call to a
For every request sent to the Barion API, you have to authenticate yourself. Use a different type of authentication depending on the type of endpoint.
Shop-level endpoints can be authenticated using the shop's unique POSKey. For more details on using and obtaining the POS key, see Barion Shop Authentication.
You can authenticate yourself to endpoints requiring wallet-level authentication via an API key called a Wallet key. For more information on using this API key, see Barion Wallet Authentication.
Handling the response
The structure of the response varies from endpoint to endpoint however you can find one property in all of them. Every API response contains an
Errors array. If this array is empty then the request was processed successfully. This array can contain multiple errors so make sure that the integration is prepared for this. The errors have the following fields:
|The error code of the payment, can be interpreted as an error Id.
|The title of the error, is a more readable form of the error.
|The description of the error, more information about the error.
|The URL of the API endpoint to help the reproduction of the error scenario.
|The e-mail address of the caller to help the reproduction of the error scenario.
|The timestamp of the response.
|If the error is related to a business process that involves a given payment, the public identifier of the payment is supplied here. This property is not present for all errors.
Example error response
The following example shows an error case where the shop does not have an account with the currency it specified when trying to create a payment. This is a validation error, so the payment identifier is not applicable.
"Title": "Payment is not supported",
"Description": "Payment is not supported. The POS doesn’t have an account that supports EUR!",
"AuthData": "[email protected]",
The following example shows a case where after several successful token charges, the customer deleted their payment card from the Barion system, so the subsequent attempt failed.
"Title": "The original payment card does not exist!",
"Description": "The payment card that was used for the original payment with recurrence ID 'TEST-01' no longer exists in the system!",
"AuthData": "[email protected]",
Refer to the Security Measures for more information on IT security before starting to code.