Calling the API

From Barion Documentation
Revision as of 06:35, 6 February 2017 by Vinczei (talk | contribs) (Protocols and data)
Jump to navigation Jump to search

Calling the Barion API

This article is incomplete. It may change significantly without any notice, so don't rely on any content you find here yet. Please check back later.

The Barion API

Barion offers you a RESTful API service to communicate with your web or mobile merchant services. Learn more about RESTful behavior the original Wikipedia article.

Protocols and data

The Barion API communicates via standard HTTP1.1 GET or POST requests. A given API endpoint accepts only GET or only POST requests - there are no universal endpoints available. On an API endpoint reference page, you can find the path of the API endpoint and the HTTP method it accepts.


POST /v2/Payment/Start

If the caller uses an incorrect method, the system responds with an XML error message.

Example: calling a POST endpoint with a GET request

  <Message>The requested resource does not support http method 'GET'.</Message>

Important: all communication must be done via HTTPS.

The API sends and receives all content in standard JSON (JavaScript Object Notation) string format. JSON strings should be UTF-8 encoded.

The data types used in the API communication are the following:

Data type Type description
string Standard character string. The Barion API uses UTF-8 encoding.
int 32-bit signed integer format
GUID (Global Unique Identifier) A 128-bit long hexadecimal identifier with 32 character representation, like this: 21EC2020-3AEA-4069-A2DD-08002B30309D. Its value is always unique in the Barion system. This is used e.g. to identify payments.
DateTime Date and time vaélues, represented in a string format of the ISO-8601 standard, like this: 2014-12-06T08:35:46Z. All API call responses contain datetimes as strings.
bool Boolean true or false values.

Note: avoid integer or byte evaluation when constructing the request JSON!

byte 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:

Base URL for API requests in the Sandbox (test) environment: (learn more about the Sandbox environment here)

Note: Always double check that you are connecting to the proper environment to avoid unnecessary hassle and troubleshooting!

API versioning

To avoid breaking changes, whenever there is a major update to an API endpoint, it is moved to a higher level of API version. At the moment, the Barion API offers two different API versions (noted v1 and v2). Some API endpoints are only available in v1 or v2. See the reference page of a given API endpoint to see which versions are available.

Note: Though version numbers can be omitted from the endpoint path (such requests always fall back to v1), it is recommended to always specify the API version when sending requests to the Barion API to avoid confusion.