About Wallet API

Wallet API is composed of two different but related features:

  1. To get information about Paysera system's user and her account;
  2. To make payments between Paysera accounts. This includes sending, receiving and coordinating payments.

Terms used in API

Most of the terms represent resources, available in API. For more detailed descriptions please refer to documentation available in other specification chapters.
Client
This is used to refer to API client - your script or application, which makes requests to the API. Client permissions are configurable and also depends on client type (web-based client, mobile application, physical location etc.)
Project
Project has owner and default account for incoming payments. Several different clients can make requests representing same project. Similarly, one client sometimes can represent few different projects.
User
Registered user in Paysera system. Can be a person or a company.
Account
Account with balance, belonging to some user. Users can have permissions to use other accounts than their own, this is always the case for company's accounts - only persons can access them.
Wallet
Wallet is always related to some user and some account. Each user can have one or more wallets, each of them can have different limits, options etc. Wallet can be related to some card or other identifier, so it's possible for user to have few wallets, related to same account.
Allowance, Payment and Transaction
Transaction is combination of Payment(s) and possibly an Allowance. User confirms transaction in web page, by providing some secret information like PIN or in advance by using an allowance. Transaction is related to specific wallet, it's limits are used to validate the payments. Each payment has beneficiary, which is also a wallet, usually belonging to the project.

API Basics

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

Paysera system provides JSON encoded response to every request. HTTP status code identifies the status of the request - on successful requests, status code 200 is returned. In case of error, some information like code and description is provided to debug the problem more easily, so client should try to decode the response even if 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 element will definitely exist if it's optional.

Errors and response codes

On success, API returns status code 200. In case of error, status code differs from case to case. Client should always check response status code to know what kind of response is given. In case of any error, response body is an 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 these:
  • 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 were not provided or are incorrect
  • forbidden (status code 403) - Client has no rights to access requested resource or make 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 methods descriptions.

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

All API calls must be authenticated. Currently two authentication schemes are used:

  • By using MAC access authentication - providing signature of request as a header in each request. Shared secret key is used, but never sent with request. This authentication protocol is always used to provide access token (getting user's information).
  • By using SSL client certificate. Before using this protocol, client's owner provides certificate request for Paysera administrators. Certificate request is signed and certificate is provided back to client's owner. This certificate, together with related private key, is used to sign every API request. This method is safer as the secret is never shared with Paysera system - private key is known only to client.

In any case, all requests to the Paysera system are made using HTTPS protocol. Paysera system always authenticates client, but client needs to be sure that authentication on Paysera server is made too. For all API calls certificate of Paysera server must be checked to be valid. This protects from DNS spoofing, MITM and similar attacks.

MAC access authentication

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

Before using API, you must register your app in Paysera system. Currently public registration is not yet available, please contact our support to register client for this API. You will be provided with your credentials, for example:

client_id:     wkVd93h2uS
mac_key:       IrdTc8uQodU7PRpLzzLTW6wqZAO6tAMU
mac_algorithm: hmac-sha-256
Important mac_key must be kept secret at all times.
Info You are recommended to use provided libraries that do most of authentication work for you, if one is available for your programming language
Info All MAC authentication header examples in this specification are valid and generated with these credentials

At every request to API client must construct authentication header by calculating an UNIX timestamp and generating a random string used as a nonce. From these values together with HTTP request method, request URI, hostname, port and mac_key client has to calculate hash using the algorithm defined by mac_algorithm. This calculated hash is mac value, which must be included in the authorization header.

Authorization header

Authorization header must contain authorization protocol (MAC) and these parameters:
  • id - ID assigned to the client making the request (client_id);
  • ts - calculated UNIX timestamp;
  • nonce - randomly generated value; only characters in ranges %x20-21 / %x23-5B / %x5D-7E can be used;
  • mac - calculated hash of request values and mac_key;
  • ext - extension to MAC protocol. May contain parameter body_hash and extra parameters project_id, location_id. Parameters are URL-encoded. body_hash is result of sha256 and base64 encoded request content if it's present. If there is no content, body_hash should be omitted. ext can be empty if there are no any parameters, including body_hash.
Example:
GET /rest/v1/payment/10145 HTTP/1.1
Host: wallet.paysera.com
User-Agent: PayseraApi library
Authorization: MAC id="wkVd93h2uS", ts="1343818800", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="xTCR/i6LKbhXoo4Fe77ECowrn+Q6uUdX7yxwS/lhDWU=", ext="body_hash=ob%2FZf8GBHrgpuw5xc3esSw2NYiOG9N9AQKAm%2FMpElfs%3D&project_id=1"

Calculating MAC value

mac value is calculated from normalized request string and mac_key parameter.

Normalized request string

The normalized request string is constructed by concatenating together, in order, the following HTTP request elements, each followed by a new line character (%0A when urlencoded, \n in most of programming languages):
  1. timestamp;
  2. nonce;
  3. HTTP request method in upper case;
  4. HTTP request URI;
  5. Host request header in lower case;
  6. Request port - in this API always 443;
  7. The value of ext field - URL-encoded string containing various extra parameters.
An example - request and corresponding normalized request string, \n given just for clarity and represents new line character:
GET /rest/v1/payment/10145 HTTP/1.1
Host: wallet.paysera.com
User-Agent: PayseraApi library
1343818800\n
nQnNaSNyubfPErjRO55yaaEYo9YZfKHN\n
GET\n
/rest/v1/payment/10145\n
wallet.paysera.com\n
443\n
\n
Warning New line character must be put after each of elements, even after the last one when it is just an empty string

MAC calculation algorithm

If MAC algorithm is hmac-sha-256, mac is calculated using HMAC algorithm together with the sha256 hash function:
mac = HMAC-SHA256(mac_key, normalizedRequestString)

Please refer to HMAC and SHA256 specifications for more details on these algorithms.

Result is provided as binary result, encoded in base64.

SSL client certificate authentication

When using this authentication scheme, no additional headers are needed. To register certificate with Paysera system, certificate request must be provided for out administrators to generate the signed certificate.

Before generating certificate request, private key must be generated. Always keep private key securely and don't provide it even to Paysera administrators.

For example, certificate request can be generated using openssl command line client:

openssl genrsa -out private.pem 2048
openssl req -new -key private.pem -out certificate_request.csr

Country Name (2 letter code) [AU]:LT
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:Vilnius
Organization Name (eg, company) [Internet Widgits Pty Ltd]:UAB Some Company
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:example.com
Email Address []:info@example.com

Client types and permissions

Each client that use Wallet API has different permissions and configuration. Some of the permissions depends on the type of the client. Available client types:

private_client
This client can be related to one project or manage several of them. 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 is integrated into the application package. This client can only make calls for Client resource - get it's information or register new client.
app_client
This client is created dynamically by application client, when mobile application is installed into the device. Thus each device makes calls from different clients - they cannot access each other transactions or make some other actions, related to any other client of the same application.

Extra parameters

Request may contain such extra parameters:
  • project_id. Defines the specific project. Should be used if client makes calls for several projects or if making calls with access token and scope projects.
  • location_id. Defines the specific location. Should be used if specific location is known which is initiating payment or any other action. Location can influence allowance usage, also it's address or other information can be provided together with payment details for the user.
In case of MAC access authentication, extra parameters should be passed using ext authentication field. If authentication method is SSL client certificate, each extra parameter must be defined in separate HTTP header. Parameter must be converted to comply 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: WebToPayApi library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="Qj0PSwlPicgVGbJ54uvVd6nX3t6bTl8mz1S0x5tLsKY="

MAC authentication

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

Getting server information

About

This method returns information about the server - currently only the time. This method can be used to synchronize clocks between client and the server. This should always be done if time in the client system may change, for example when making requests from 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: WebToPayApi 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
}