Wallet API is composed of two different, but related features:
- To get information about Paysera system's user and his/her account;
- To make payments between Paysera accounts. This includes sending, receiving and coordinating payments.
Terms used in APIMost of the terms represent resources, available in API. For more detailed descriptions please refer to the documentation available in other chapters of the specification.
- 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.)
- 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.
- A registered user in Paysera system. It can be a person or a company.
- 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.
- 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.
How to start?
Step 1. Read the documentation
First of all, before continuing you should read the documentation to find out if it's the right tool, which you are looking for.
Step 2. Get Paysera account
There are two types of accounts which could be used with an integration:
Productionis used as a real environment. To obtain an account register in Paysera.
Sandboxis used as a developing environment. To obtain an account, register in Paysera Sandbox.
Step 3. Sign an Agreement
Contact Paysera with a description of how are you going to use specific API, which API will be used
and will it be used with
Sandbox. You might be asked to provide
Signing an agreement can be skipped if Sandbox environment will be used, but we strongly advise to sign an agreement
at any case, as only with an agreement you might be sure,
that we will allow using our services in
Step 4. Get API client configured
Read the chapter about Authentication and choose the method you prefer, inform Paysera about your selection. It takes time to configure all, so when it will be ready, we will send credentials to your specified address.
Production environments are different, so you won't be able to use the same
credentials from one environment on another.
Sandboxclient can be configured without an agreement, while
Productionclient requires an agreement.
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 w ith 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
mac_keymust be kept secret at all times.
At each request to API the client must construct an authentication header by calculating the UNIX
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
mac_algorithm. This calculated hash is
mac value, which must be included in the
Authorization headerAuthorization header must contain the authorization protocol (
MAC) and the following parameters:
id- ID assigned to the client making the request (
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
ext- extension to MAC protocol. May contain parameter
body_hashand extra parameters
location_id. Parameters are URL-encoded.
body_hashis the result of sha256 and base64 encoded request content if it's present. If there is no content,
body_hashshould be omitted.
extcan be empty if there are no parameters, including
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
macvalue is calculated from the normalized request string and
Normalized request stringThe normalized request string is constructed by concatenating together, in order, the following HTTP request elements, each followed by a new line character (
\nin most of programming languages):
- HTTP request method in upper case;
- HTTP request URI;
Hostrequest header in lower case;
- Request port - in this API always
The value of
extfield - 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 algorithmIf MAC algorithm is
macis 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.
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 :email@example.com
An optional company name when generating a certificate request