Calling the API: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
 
(16 intermediate revisions by 6 users not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
{{PageTitle|title=Calling the Barion API}}
{{PageTitle|title=Calling the Barion API}}
{| style="margin-left:2em;" align="right"
| __TOC__
|}


== 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 [https://en.wikipedia.org/wiki/Representational_state_transfer|in the original Wikipedia article].
Barion offers you a RESTful API service to communicate with your web or mobile merchant services. Learn more about RESTful behavior [https://en.wikipedia.org/wiki/Representational_state_transfer in the original Wikipedia article].
 
{{NotificationBox|title=IMPORTANT|text=All communication must be done over HTTPS. The Barion system supports TLS v1.2 / v1.3|color=#FF7A3D}}


== Protocols and communication ==
== Protocols and communication ==


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.
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.
On each API endpoint reference page, you can find the path of the API endpoint and the HTTP method it accepts.
Each API endpoint reference page lists the path of the API endpoint and the HTTP method it accepts.


Example:
Example:
Line 17: Line 23:
|uri=/v2/Payment/Start
|uri=/v2/Payment/Start
}}
}}
{{NotificationBox|title=IMPORTANT|text=All communication must be done over HTTPS. The Barion system only supports TLS v1.1 / v1.2|color=#FF7A3D}}
{{NotificationBox|title=WARNING|text=TLS 1.0 will be switched off on the 20th of July 2018 on the live servers, switch to TLS 1.1 / 1.2 now!|color=#FF0000}}


If the caller uses an incorrect method, the system responds with a JSON error message.
If the caller uses an incorrect method, the system responds with a JSON error message.
Line 28: Line 30:
<source lang="json">
<source lang="json">
{
{
   "Message": "The requested resource does not support http method 'GET'."
   "Message": "The requested resource does not support HTTP method 'GET'."
}
}
</source>
</source>
====== Timeout ======
The maximum duration for an HTTP request is 30 seconds. After that the server stops the request.


== Data and content types ==
== Data and content types ==
Line 36: Line 41:
The API sends and receives all content in standard '''JSON''' (JavaScript Object Notation) string format.
The API sends and receives all content in standard '''JSON''' (JavaScript Object Notation) string format.


Some things you must ensure when creating an API request:
Ensure your API requests meet these requirements:
* JSON strings are UTF-8 encoded.
* JSON strings are UTF-8 encoded.
* The MIME type of the request sent to the API is defined as <code>application/json</code>.
* The MIME type of the request sent to the API is defined as <code>application/json</code>.
* <code>Content-length</code> should also be specified explicitly in all HTTP request headers.
* Explicitly specify <code>Content-length</code> in all HTTP request headers.


The data types used in the API communication are the following:
The data types used in the API communication are the following:
Line 55: Line 60:
|-
|-
| GUID (Global Unique Identifier)
| GUID (Global Unique Identifier)
| A 128-bit long hexadecimal identifier with 32 character string 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. For security and compatibility reason the GUID is used without hyphens for most of our API.
| 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.
|-
|-
| DateTime
| DateTime
| Date and time values, 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.
| 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.
|-
|-
| TimeSpan
| TimeSpan
Line 65: Line 70:
| bool
| bool
| Boolean <code>true</code> or <code>false</code> values.  
| Boolean <code>true</code> or <code>false</code> values.  
'''Note:''' avoid integer or byte evaluation when constructing the request JSON!
'''Important:''' Avoid integer or byte evaluation when constructing the request JSON.
|-
|-
| byte
| byte
Line 79: Line 84:
Base URL for API requests in the '''Sandbox (test)''' environment: <code>https://api.test.barion.com</code> (learn more about the Sandbox environment [[Sandbox|here]])
Base URL for API requests in the '''Sandbox (test)''' environment: <code>https://api.test.barion.com</code> (learn more about the Sandbox environment [[Sandbox|here]])


'''Note:''' Always double check that you are connecting to the proper environment to avoid unnecessary hassle and troubleshooting!
{{NotificationBox|title=IMPORTANT|text=Always double-check that you are connecting to the proper environment.|color=#FF7A3D}}


== API versioning ==
== 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 <code>v1</code> and <code>v2</code>). 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.
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 <code>v1</code> and <code>v2</code>). 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 <code>v1</code>), it is recommended to always specify the API version when sending requests to the Barion API to avoid confusion.
'''Note:''' Though version numbers can be omitted from the endpoint path (such requests always fall back to <code>v1</code>), we recommend always specifying the API version when sending requests to the Barion API to avoid confusion.


Example paths:
Example paths:
Line 94: Line 99:


== Authentication ==
== Authentication ==
{{NotificationBox|title=IMPORTANT|text=Some endpoints can only be authenticated with username/password combination (eg.: [[Statement-Download-v2|v2/Statement/Download]].<br/> Should you use this feature, please contact customer support, and request this type of authentication to be enabled on api). Should you |color=#FF7A3D}}


For every request sent to the Barion API you have to authenticate yourself. For this every API request should cointain a <code>POSKey</code> property containing the secret API key for the shop. This key is in the confirmation e-mail that was sent to you when you opened the shop or can be copied from the details page of the shop (secure.barion.com -> Manage my shops -> Details). This is unique for every shop in the system. Be aware that 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:
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 ====


[[File:Poskey.jpg]]
Shop-level endpoints can be authenticated using the shop's unique <tt>POSKey</tt>. For more details on using and obtaining the POS key, see [[Barion Shop Authentication]].


If the key is invalid you will receive an <code>AuthenticationFailed</code> error.
==== Wallet-level endpoints ====
 
You can authenticate yourself to endpoints requiring wallet-level authentication via an API key called a <tt>Wallet key</tt>. For more information on using this API key, see [[Barion Wallet Authentication]].


== Handling the response ==
== Handling the response ==
The structure of the response varies from endpoint to endpoint however on property can found in all of them. Every API response contains an <code>Errors</code> 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 structure of the response varies from endpoint to endpoint however you can find one property in all of them. Every API response contains an <code>Errors</code> 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:


{| class="wikitable api-table"
{| class="wikitable api-table"
! FieldName || Description
! FieldName || Description
|-
|-
| ErrorCode || The error code of the payment, this can be interpreted as an error Id.
| ErrorCode || The error code of the payment, can be interpreted as an error Id.
|-
|-
| Title|| The title of the error, this is a more readable form of the error.
| Title|| The title of the error, is a more readable form of the error.
|-
|-
| Description|| The description of the error, more information about the error.
| Description|| The description of the error, more information about the error.
Line 119: Line 127:
|-
|-
| HappenedAt || The timestamp of the response.
| HappenedAt || The timestamp of the response.
|-
| PaymentId ||  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.
|-
|-


Line 124: Line 134:


'''Example error response'''
'''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.
<source lang=json>
{
  "Errors": [
    {
      "ErrorCode": "NotExistingCurrency",
      "Title": "Payment is not supported",
      "Description": "Payment is not supported. The POS doesn’t have an account that supports EUR!",
      "EndPoint": "https://api.barion.com/v2/Payment/Start",
      "AuthData": "[email protected]",
      "HappenedAt": "2017-02-06T09:48:13.7694921Z"
    }
  ]
}
</source>
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.
<source lang=json>
<source lang=json>
{
{
   "Errors": [
   "Errors": [
     {
     {
       "ErrorCode": "NotExistingPaymentId",
       "ErrorCode": "OriginalPaymentCardDoesNotExist",
       "Title": "The given payment id is invalid",
       "Title": "The original payment card does not exist!",
       "Description": "The given payment id(510bbd38-08c9-40b9-9e21-c6f6cb9eb4f1) is invalid!",
       "Description": "The payment card that was used for the original payment with recurrence ID 'TEST-01' no longer exists in the system!",
       "EndPoint": "https://api.barion.com/v2/Payment/GetPaymentState?POSKey=5b65f8f7a5f4405bb19495383dcf170a&PaymentId=510bbd3808c940b99e21c6f6cb9eb4f1",
       "EndPoint": "https://api.barion.com/v2/Payment/Start",
       "AuthData": "[email protected]",
       "AuthData": "[email protected]",
       "HappenedAt": "2017-02-06T09:48:13.7694921Z"
       "HappenedAt": "2017-02-06T09:48:13.7694921Z"
Line 140: Line 171:


==Security==
==Security==
Please refer to the [[Security Measures]] page for more information on IT security before staring to code.
Refer to the [[Security Measures]] for more information on IT security before starting to code.

Latest revision as of 13:23, 15 January 2024

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.

IMPORTANT
All communication must be done over HTTPS. The Barion system supports TLS v1.2 / v1.3

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.

Example:

POST /v2/Payment/Start

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'."
}
Timeout

The maximum duration for an HTTP request is 30 seconds. After that the server stops the request.

Data and content types

The API sends and receives all content in standard JSON (JavaScript Object Notation) string format.

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 application/json.
  • Explicitly specify Content-length in all HTTP request headers.

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 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.
DateTime 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.
TimeSpan 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.
bool Boolean true or false values.

Important: 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.

API URLs

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: https://api.barion.com

Base URL for API requests in the Sandbox (test) environment: https://api.test.barion.com (learn more about the Sandbox environment here)

IMPORTANT
Always double-check that you are connecting to the proper environment.

API versioning

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 v1 and 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.

Example paths:

  • https://api.barion.com/Transaction/List - implicit call to a v1 endpoint (version number is omitted from path)
  • https://api.barion.com/v1/Transfer/Send - explicit call to a v1 endpoint
  • https://api.barion.com/v2/Payment/Start - explicit call to a v2 endpoint

Authentication

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

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.

Wallet-level endpoints

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:

FieldName Description
ErrorCode The error code of the payment, can be interpreted as an error Id.
Title The title of the error, is a more readable form of the error.
Description The description of the error, more information about the error.
EndPoint The URL of the API endpoint to help the reproduction of the error scenario.
AuthData The e-mail address of the caller to help the reproduction of the error scenario.
HappenedAt The timestamp of the response.
PaymentId 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.

{
  "Errors": [
    {
      "ErrorCode": "NotExistingCurrency",
      "Title": "Payment is not supported",
      "Description": "Payment is not supported. The POS doesn’t have an account that supports EUR!",
      "EndPoint": "https://api.barion.com/v2/Payment/Start",
      "AuthData": "[email protected]",
      "HappenedAt": "2017-02-06T09:48:13.7694921Z"
    }
  ]
}

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.

{
  "Errors": [
    {
      "ErrorCode": "OriginalPaymentCardDoesNotExist",
      "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!",
      "EndPoint": "https://api.barion.com/v2/Payment/Start",
      "AuthData": "[email protected]",
      "HappenedAt": "2017-02-06T09:48:13.7694921Z"
    }
  ]
}

Security

Refer to the Security Measures for more information on IT security before starting to code.