English

API basics

API is based on REST principles. The client makes HTTP requests to Paysera system, providing information about the intended action. HTTP verbs GET, POST, PUT and DELETE are used in this API. In POST and PUT requests content request is usually provided in JSON format by using UTF-8 encoding. If some other format is used, it is specified in the method description.

Paysera system provides JSON encoded response to each request. HTTP status code identifies the status of the request - for successful requests, status code 200 is returned. In case of an error, some information like a code and description is provided to debug the problem more easily, so that the client could try to decode the response even if an error code is returned.

If some elements of returned structure are optional, they can be skipped. That is, null is not returned, the JSON element is entirely skipped. Client should handle these situations and do not assert that the element will definitely exist if it's optional.

Errors and response codes

In case of a success, API returns status code 200. In case of an error, the status code differs from case to case. The client should always check the response status code to know what kind of response is given. In case of an error, response body is the error object. It's structure is provided in the table below.

Parameter
Type
Remarks
Description
error
string
always
Code of the error. One of defined in this API
error_description
string
not always
Description of the error
error_uri
string
not always
Link to the site explaining the error or how to avoid it

Basic error codes

Error code
Status code
Description
invalid_request
400
Request content is invalid
invalid_parameters
400
Some required parameter is missing or it's format is invalid
unauthorized
401
Authentication parameters are not provided or are incorrect
forbidden
403
The client has no right to access the requested resource or perform the requested action
not_found
404
Resource was not found
not_acceptable
406
Unknown request or response format
invalid_state
409
Requested action cannot be made to the current state of resource
internal_server_error
500
Unexpected internal system error

Error response example

HTTP/1.1 403 Forbidden
Content-type: application/json;charset=utf-8
{
    "error": "forbidden",
    "error_description": "This resource is assigned to other project, client has no rights to read it"
}

Authentication

MAC access authentication used in API is based on the OAuth 2.0 Message Authentication Code (MAC) Tokens specification .

project_id is used as a mac_id and project_sign_password is used as mac_secret.