About Wallet API

Wallet API is composed of two different, but related features:

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

Terms used in API

Client

This one is used to refer to the API client - your script or application, which makes requests to the API. Client permissions are configurable and also depend on the client type (web-based client, mobile application, physical location etc.)

Project

The project has an owner and a default account for incoming payments. Several different clients can make requests representing the same project. Similarly, one client sometimes can represent several different projects.

User

A registered user in Paysera system. It can be a person or a company.

Account

An account with balance, belonging to a 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

A wallet is always related to a certain user and a certain account. Each user can have one or more wallets, each of them can have different limits, options etc. A wallet can be related to a card or other identifier, so it's possible for a user to have several wallets, related to the same account.

Allowance, Payment and Transaction

A transaction is a combination of Payment(s) and possibly an Allowance. The user confirms the transaction on a web page by providing some secret information, like PIN, or in advance by using an allowance. The transaction is related to a specific wallet and it's limits are used to validate the payments. Each payment has a beneficiary, which is also a wallet, usually belonging to the project.

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

• 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

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

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

MAC access authentication

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

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

client_id:     wkVd93h2uS
mac_key:       IrdTc8uQodU7PRpLzzLTW6wqZAO6tAMU
mac_algorithm: hmac-sha-256

At each request to API the client must construct an authentication header by calculating the UNIX timestamp and generating a random string used as a nonce. From these values, together with the HTTP request method, request URI, hostname, port and mac_key, the 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

• 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 the 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 parameters, including body_hash.

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

Normalized request string

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.

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

MAC calculation algorithm

mac = HMAC-SHA256(mac_key, normalizedRequestString)

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

The result is provided as a binary result, encoded in base64.

SSL client certificate authentication

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

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

For example, the 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 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

• 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.

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

About

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.

Request

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

Response data structure

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

About

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

Request

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

Response data structure

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
}