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 (available in all API methods) are the following:
  • invalid_request (status code 400) - Request content is invalid
  • invalid_parameters (status code 400) - Some required parameter is missing or it's format is invalid
  • invalid_state (status code 409) - Requested action cannot be made to the current state of resource
  • unauthorized (status code 401) - Authentication parameters are not provided or are incorrect
  • forbidden (status code 403) - The client has no right to access the requested resource or perform the requested action
  • not_found (status code 404) - Resource was not found
  • internal_server_error (status code 500) - Unexpected internal system error
  • not_acceptable (status code 406) - Unknown request or response format
Some other probable error codes are provided in descriptions of methods.

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"
}

Client types and permissions

Each client who uses the Wallet API has different permissions and configuration. Some of the permissions depend on the type of the client. Available client types:

private_client - This client can be related to one project or manage several of them. The client is based on the web or offline location, not accessible by 3rd party persons.

application - This client is related to one project and is used for every mobile application. Credentials for this client are integrated into the application package. This client can only make calls for the Client resource - get it's information or register a new client.

app_client - This client is created dynamically by the application client, when a mobile application is installed into the device. Thus, each device makes calls from different clients - they cannot access each others transactions or make some other actions, related to any other client of the same application.

Extra parameters

The request may contain the following extra parameters:
  • project_id. Defines the specific project. Should be used if the client makes calls for several projects or when making calls with access token and scope projects.
  • location_id. Defines the specific location. Should be used if the specific location initiating a payment or any other action is known. The location can influence the allowance usage, and it's address or other information can be provided for the user together with payment details.
In case of MAC access authentication, extra parameters should be passed using ext authentication field. If the authentication method is the SSL client certificate, each extra parameter must be defined in a separate HTTP header. The parameter must be converted to comply with HTTP header naming conventions and prefixed with Wallet-Api-, for example: Wallet-Api-Project-Id, Wallet-Api-Location-Id.

Example request

SSL client authentication

GET /rest/v1/wallet/14471/balance HTTP/1.1
Host: wallet.paysera.com
Wallet-Api-Project-Id: 3
User-Agent: Some library with version and environment

MAC authentication

GET /rest/v1/wallet/14471/balance HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="EOhN6gBf49tR2KxMflaaiN7bBVGDhfG6co8gcSBLyiQ=", ext="project_id=3"

Getting server information

This method returns information about the server - currently, only the time. This method can be used to synchronize clocks between the client and the server. This should always be done if time in the system of the client can change, for example, when making requests from a mobile phone.

Info This method does not require any authentication

Request

GET https://wallet.paysera.com/rest/v1/server

Response data structure

Parameter
Type
Remarks
Description
time
integer
always
Current server time in UNIX timestamp

Example request

GET /rest/v1/server HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="0SiVJuv1zLJzQaw3dtKkZ4++CUs9CwCHI54s/rAsSnQ="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "time": 1383116734
}

Accessing server configuration variables

This method returns information about the server configuration, for example, current minimum password length.

Info This method does not require any authentication

Request

GET https://wallet.paysera.com/rest/v1/configuration

Response data structure

Parameter
Type
Remarks
Description
minimum_password_length
integer
always
Minimum password length

Example request

GET /rest/v1/configuration HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="gBv9XvvX/yhgpuwH7ooOmv1S5Un9G/QbJ/eetFbuGzc="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "minimum_password_length": 8
}