English

User Resource

Get user information

This method returns information about the user.

Requesting user by ID

GET https://wallet.paysera.com/rest/v1/user/:id

Parameters

id - id of the user. Can be integer or me (if access token is used)

Requesting user by other information

GET https://wallet.paysera.com/rest/v1/user?person_code[:nationality]=:person_code&email=:email&phone=:phone

Parameters

person_code - person's identification code

nationality - person's nationality (country to which person code belongs) in ISO 3166-1 alpha-2 format

email - person's confirmed email address

phone - person's confirmed phone number; must start with country code and without 00 or + sign

Info Only one of parameters can be passed to search only by that criteria. person_code always comes with nationality
Warning API client must have special permissions configured to be able to search by person's code
Warning Be sure to validate phone number for country code before passing to API - 86 is country code for China

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of the user
email
string
only if current access token has scope email or scope email_offline was confirmed;
only if currently available for this user
Verified email of this user
phone
string
only if current access token has scope phone or scope phone_offline was confirmed;
only if currently available for this user
Verified phone of this user
address
object
only if current access token has scope address or scope address_offline was confirmed;
only if currently available for this user
Address of this user
dob
string
only if current access token has scope dob or scope dob_offline was confirmed;
only if currently available for this user
User's date of birth in format yyyy-mm-dd
gender
string
only if current access token has scope gender or scope gender_offline was confirmed;
only if currently available for this user
Gender of this user. One of the following: male, female
identity
object
only if current access token has scope identity or full_name, or scope identity_offline or full_name_offline or confirmed;
only if currently available for this user
Verified email of the user
identification_level
string
only if current access token has scope identification_level or identification_level_offline confirmed;
Identification level of the user
type
string
this parameter is not returned by default and is enabled only for some clients
Returns type of client: legal, natural
calculated_level
string
only if current access token has scope identification_level or identification_level_offline confirmed;
Calculated identification level of the user
wallets
array of integer
only if current access token has scope wallet_list or scope wallet_list_offline was confirmed
List of wallet IDs belonging to this user
options
object
only if available for current user
Options for the user
pep
array
only if current access token has scope politically_exposed_persons
List of politically exposed persons of the user

Address data structure

Parameter
Type
Remarks
Description
country
string
always
Country code of address in ISO 3166-1 alpha-2 format
city
string
always
City or state title
street
string
always
Street title together with house and flat numbers
post_index
string
only if available
Post index

Identity data structure

Parameter
Type
Remarks
Description
name
string
always
Confirmed name(-s) of the user
surname
string
always
Confirmed surname of the user
nationality
string
only if scope identity is active
Country code in ISO 3166-1 alpha-2 format
code
string
only if scope identity is active
Unique identification code for this person, format depends on the nationality of the user

Options data structure

Parameter
Type
Remarks
Description
default_currency
string
always
Default currency for this user

Identification levels

Identification level
Description
unidentified
1 - Starter
semi_identified
2 - Basic
identified
3 - Standard
fully_identified
4 - Unlimited

Pep data structure

Parameter
Type
Remarks
Description
name
string
only if a close family member or an associate was added
Name of member or associate member
relation
string
only if a close family member or an associate was added
Relation type with member or associate
positions
array
always
Positions in politics

Example request

GET /rest/v1/user/221 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="9JanJHwnBfPdahjqd0I+kzbdEM/TRVY/h3xtAhzjos0="
Info In this example we are requesting information about user which ID is 221

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 221,
    "email": "something@example.com",
    "phone": "37066612345",
    "address": {
        "country": "lt",
        "city": "Vilnius",
        "street": "Lauko g. 1"
    },
    "dob": "1910-01-23",
    "gender": "male",
    "identity": {
        "name": "John",
        "surname": "Smith",
        "nationality": "lt",
        "code": "31001230000",
        "identification_level": "fully_identified"
    },
    "wallets": [
        14471
    ],
    "options": {
        "default_currency": "EUR"
    },
    "pep": [
        {
            "name": "Bill",
            "relation": "Parents",
            "positions": [
                "head_of_state"
            ]
        }
    ]
}

Getting specific information about the user

You can also request some specific user information. When getting all information, specific element can be missing if it is not available or if you don't have permissions to access it. When requesting specific information, error with status code 403 is returned if you have no permissions to access it and error with status code 404 - if information is not currently available.

When requesting user's available wallets, response format is different than in user request - array of wallet objects is returned, not only their IDs (see wallet object response structure).

Requesting specific user information by ID

Info id of the user. Can be integer or me (if access token is used)

Getting the specific user email

GET https://wallet.paysera.com/rest/v1/user/:id/email
Example request for the specific user email
GET /rest/v1/user/221/email HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="YJoiU+AkAlYkdGXIzHR8EfC70Dd6vALDB4cN17urtZ4="
Example response
HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
"example@paysera.com"

Getting the specific user phone

GET https://wallet.paysera.com/rest/v1/user/:id/phone
Example request for the specific user phone
GET /rest/v1/user/221/phone HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="NrSooeVbipBrt4m02hAexuapxJRXucphzUduHc6GNj4="
Example response
HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
"370612312345"

Getting the specific user confirmed phones

GET https://wallet.paysera.com/rest/v1/user/:id/confirmed-phones
Example request for the specific user phone
GET /rest/v1/user/221/confirmed-phones HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="F8drQOyK2oEi/eTROdbQrLgvycvM14SFAjjnfLB8LBQ="
Example response
HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
[
    "370612312345"
]

Getting the specific user address

GET https://wallet.paysera.com/rest/v1/user/:id/address
Example request for the specific user address
GET /rest/v1/user/221/address HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="3kfDyk9vaRCu47XFvKQ3PBfQX3BR0fIeXrqZC4PVvRc="
Example response
HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "country": "lt",
    "city": "Vilnius",
    "street": "Street example 16",
    "post_index": "LT-11111"
}

Getting the specific user identity

GET https://wallet.paysera.com/rest/v1/user/:id/identity
Example request for the specific user identity
GET /rest/v1/user/221/identity HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="a/a7ZtHbFEuSWowd+7+A3t5tlWnQk7SNLrQlETn5i5w="
Example response
HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "name": "John",
    "surname": "Smith",
    "nationality": "lt",
    "code": "31001010000"
}

Getting the specific user wallets

GET https://wallet.paysera.com/rest/v1/user/:id/wallets
Example request for the specific user wallets
Parameters

id - id of the user. Can be integer or me (if access token is used)

inactive_included - By default endpoint returns only active wallets, use ?inactive_included=true to get inactive also 

GET /rest/v1/user/221/wallets HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="4ZaEVJ1lryXXR9+PJgjROWAjGZE1/VVuFzCik3uJqGw="
Example response
HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
[
    {
        "id": 14471,
        "owner": 221,
        "account": {
            "number": "EVP0010001000101",
            "owner_title": "John Smith",
            "description": "My personal account"
        },
        "status": "active"
    },
    {
        "id": 14472,
        "owner": 221,
        "account": {
            "number": "EVP3210001000102",
            "owner_title": "Company Inc."
        },
        "status": "active"
    }
]

Getting user's services

These methods allow to get or enable user services. To use these methods services scope is required.

Services list

Services list with their description are provided below.

Service
Description
affiliate
User is participant in affiliate program
macro
User is collecting macro payments
micro
User is collecting micro payments
offline
User is offline
payment_instruments
User is using payment instruments
paysera_app
User is using paysera app
sms_bank
User is using sms bank service

Service data structure

Parameter
Type
Remarks
Description
service
string
always
Service key
status
string
always
Service status. One of these values: enabled, disabled
title
string
always
Service title
actions
array of strings
always
Array of allowed actions. One of these values: enable, disable
added
integer
only if service is enabled
Date in UNIX timestamp when service was enabled
url
string
always
URL to service rules (full page - HTML with layout)
url_plain
string
always
URL to service rules (basic HTML without layout)

Requesting enabled user services

GET https://wallet.paysera.com/rest/v1/user/:id/services
Parameters

id - id of the user. Can be integer or me (if access token is used)

Response data structure

Parameter
Type
Remarks
Description
user_id
integer
always
ID of the user
services
array of objects
always
Enabled user services

Example request

GET /rest/v1/user/221/services HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="N1HGqFcc6hxuabSWzYNYSPfSEQ48Ne8zPu7Mhx2Bm2s="
Info In this example we are requesting enabled services for user which ID is 221

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "user_id": "221",
    "services": [
        {
            "service": "micro",
            "status": "enabled",
            "title": "Micro",
            "actions": [
                "enable",
                "disable"
            ],
            "added": 1402406430,
            "url": "http://test.url",
            "url_plain": "http://testplain.url"
        },
        {
            "service": "offline",
            "status": "enabled",
            "title": "Offline",
            "actions": [
                "enable"
            ],
            "added": 1403864605,
            "url": "http://test.url",
            "url_plain": "http://testplain.url"
        },
        {
            "service": "macro",
            "status": "enabled",
            "title": "Macro",
            "actions": [
                "disable"
            ],
            "added": 1404201388,
            "url": "http://test.url",
            "url_plain": "http://testplain.url"
        }
    ]
}

Enabling service for user

PUT https://wallet.paysera.com/rest/v1/user/:id/service/:service
Parameters

id - id of the user. Can be integer or me (if access token is used)

service - Service key

Example request

PUT /rest/v1/user/221/service/macro HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="mI95WuvEkvM12/inG8Ol9bFvyXqJAn/YDzTDPdEyGgA="
Info In this example we are enabling macro service for user which ID is 221

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "service": "macro",
    "status": "enabled",
    "title": "Macro",
    "actions": [
        "disable"
    ],
    "added": 1404376087,
    "url": "http://test.url",
    "url_plain": "http://testplain.url"
}

Register new user

Info This feature is not available by default and is enabled only for some clients
This method allows to register new user in Paysera system.

Request

POST https://wallet.paysera.com/rest/v1/user

Request body structure

Parameter
Type
Remarks
Description
email
string
required if phone and credentials are not specified
Email address of the user
phone
string
required if email and credentials are not specified
Phone number of the user. Must start with country code and without 00 or + sign
locale
string
optional
Locale of the user. Currently these values are supported: en, lt, ru
identity
object (see structure below)
optional
Name, surname and personal code of the user
credentials
object (see structure below)
required if email and phone are not specified
Login credentials for Paysera system
card
object (see structure below)
optional
Card data, related to the user
parameters
object (see structure below)
optional
Additional parameters for request
Warning Some keys are available only for some clients with special permissions. Moreover, some combinations for provided data can be invalid.

Identity data structure

Parameter
Type
Remarks
Description
name
string
required if surname is provided
Real name(s) of the user
surname
string
required if name is provided
Surname(s) of the user
nationality
string
required if code is provided
Person's nationality (country to which person code belongs) in ISO 3166-1 alpha-2 format
code
string
required if nationality is provided
Person's identification code. Always comes together with nationality
Info Name and surname can be passed with registration request, nationality and code can be passed only by clients with special permissions.

Credentials data structure

Parameter
Type
Remarks
Description
type
string
required
Type of credentials. Available values: main-password, pre-salt-sha1-base64. Types are detailed below
password
string
required
Password in plain text or a hash of the password, depending on the type parameter
password_salt
string
required only for some type values
Salt value, used for hashing the password
username
string
required only for some type values
Username for logging in Paysera system

Depending on the type parameter, other values may be required or unavailable to use:

main-password - Permanent password to Paysera system is provided. This is used when new user registers with Paysera system, client must not save the password. With this type, password parameter is user's provided password in plain text, password_salt and username parameters are unavailable. email or phone must also be provided when using this type of credentials

pre-salt-sha1-base64 - This type is used for providing custom credentials, already available in client's system - this is for migrating users to Paysera system. With this type, password parameter is the hash of the password, password_salt and username parameters are also required. email and phone parameters are unavailable if this type is used - if email address or phone number is known, client doesn't need to provide credentials, as the user will get instructions how to provide a new one in Paysera system.
password_salt is provided in base64 format. Plain password is prefixed with password_salt in binary format, password is SHA-1 hash result in base64 encoding.
Password hashing algorithm: 

password = base64_encode(sha1(base64_decode(password_salt) + plain_password))

If custom credentials are provided (not type main-password), first time that user logs to Paysera system, she will be provided with registration form, where permanent password will be provided (possible the same as provided by API). Also contact details are required - phone or email address.

If no credentials are passed, user will get notification SMS to phone or letter to email with registration instructions. However, user is able to fill funds and make transfers from her account before filling the registration form in Paysera system.

Card data structure

Parameter
Type
Remarks
Description
issuer
string
required
Identifier of the card issuer. Available values: vilniecio, paysera
number
string
required
Number of the card as is seen on the top of the card. Provided as text, even if contains only digits
Warning When providing card, two wallets will be created for the user: main and related to the card. In the response, only IDs of main wallets are provided. To get the ID of associated card, search wallet by card issuer and number.
Info When card is provided when registering user, no additional card confirmation is needed.

Parameters structure

Parameter
Type
Remarks
Description
phone_link
string
optional
Custom link to include in the SMS sent to user. Must include substring {code}, which will be replaced with the confirmation code. This is intended to provide easier phone confirmation in mobile applications, where links could open and prefill the code to the program or would make instant API call
email_link
string
optional
Custom link to include in the email sent to user. Must include substring {code}, which will be replaced with the confirmation code. This is intended to provide easier email confirmation in mobile applications, where links could open and prefill the code to the program or would make instant API call
scopes
array of string
optional
Additional scopes for confirmation code. Supported scopes: generator_phone_code - lets the same code to be used for initiating generator, so that no additional SMS message is needed; convert_currency_phone_code - lets the same code to be used with token refresh to extend current access token scope with convert_currency
Info Parameters can be provided only by clients with type app_client

Response data structure

On success API returns user object that was created. See get user information for more info. Response will contain all provided fields, not only those, which are accessible by getting user directly - to get all fields special permissions granted by the user are needed.

Errors

card_already_assigned, person_code_already_assigned, email_already_assigned, phone_already_assigned

Example request for registering user with main password

POST /rest/v1/user HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="eBXVCLxUKdb5kHFEG2P62Rjmv3cPMjbmQu6W3Hs7GUY=", ext="body_hash=aqslU%2B2JiI%2FtXkuAxcZfJT3W6J6wLavgfCt%2FR80R1CE%3D"
{
    "email": "email@example.com",
    "phone": "37066612345",
    "locale": "lt",
    "identity": {
        "name": "John",
        "surname": "Smith"
    },
    "credentials": {
        "type": "main-password",
        "password": "secretPassword22"
    },
    "parameters": {
        "phone_link": "myapp://phone_confirmation/{code}",
        "email_link": "myapp://email_confirmation/{code}"
    }
}

Example request for registering user with full identity

POST /rest/v1/user HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="0g1ATPbLN4r1/4qMbL+3PuA4gP3CxVSRZdK/LHuTbjo=", ext="body_hash=dw6npD8qCjzeCskm3%2B5HKXePepCH1%2Bgv9%2FrjzVNvrw4%3D"
{
    "phone": "37066612345",
    "identity": {
        "name": "John",
        "surname": "Smith",
        "nationality": "lt",
        "code": "31001010000"
    }
}

Example request for registering user with custom credentials

POST /rest/v1/user HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="g92wlN+ouFXcFmTaD24mCx2XzIYvKLhJ1MOTL+FaYyM=", ext="body_hash=W3RkJuVGVP%2FhFOWE27YK5D6N1IoNvbRmM9KxSUgl4ZQ%3D"
{
    "credentials": {
        "type": "pre-salt-sha1-base64",
        "password": "ZCsTcGHtfkkcjovbYy+tJzgr2SM=",
        "password_salt": "GA40QjJ+6oT+qu7eDjsJcBzVwZw=",
        "username": "johnsm"
    }
}
Info Plain password in this example is secretPassword22

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 221,
    "phone": "37066612345",
    "identity": {
        "name": "John",
        "surname": "Smith",
        "nationality": "lt",
        "code": "31001010000"
    },
    "wallets": [
        14471
    ]
}

Getting receipt for registered user

In case user is registered at some location (for offline or gateway clients), user receipt can (and must) be printed and given to the user. It is not allowed for the client to save receipt's text or display it for anyone else except the user herself.

Registration receipt request

GET https://wallet.paysera.com/rest/v1/user/:userId/receipt/registration?locale=:locale&width=:width

Parameters

userId - id of the user. Can be integer or me (if access token is used)

locale - optional parameter; locale for the text translation. Currently available locales: en, lt, ru

width - optional parameter; maximum symbol count in one line. Longer lines will be broken into separate ones

Response data structure

Parameter
Type
Remarks
Description
text
string
always
Text for the customer. New lines are separated by \r\n characters (CR + LF)

Example request

GET /rest/v1/user/221/receipt/registration?locale=en&width=35 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="5A68z9rhEL2JamyBDZ3SzQh4rjWXolMnyBxH7mGh5Xg="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "text": "You have registered in PayserarnsystemrnYour confirmation code is ABCDEF"
}

Assigning phone to user

Info This feature is not available by default and is enabled only for some clients
This method allows to assign phone number to already registered user. SMS with confirmation code is sent to provided phone number, this code should be sent with phone confirmation request after user inputs the code to the client.

Request

POST https://wallet.paysera.com/rest/v1/user/:userId/phone

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Request body structure

Parameter
Type
Remarks
Description
phone
string
required if email and credentials are not specified
Phone number of the user. Must start with country code and without 00 or + sign
parameters
object (see structure below)
optional
Additional parameters for request

Parameters structure

Parameter
Type
Remarks
Description
phone_link
string
optional
Custom link to include in the SMS sent to user. Must include substring {code}, which will be replaced with the confirmation code. This is intended to provide easier phone confirmation in mobile applications, where links could open and prefill the code to the program or would make instant API call
scopes
array of string
optional
Additional scopes for confirmation code. Supported scopes: generator_phone_code - lets the same code to be used for initiating generator, so that no additional SMS message is needed; convert_currency_phone_code - lets the same code to be used with token refresh to extend current access token scope with convert_currency

Response data structure

On success API returns user object. See get user information for more info.

Errors

phone_already_assigned, not found, rate_limit_exceeded (if current client made too many requests in some period of time)

Example request

POST /rest/v1/user/221/phone HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="Mp+ItikyWphKoUBKW96GQPwJS7pXB5+YuNYEVSStMKU=", ext="body_hash=FtpRvrnoUbS8ZJZO5KK5xJGvHku%2FqUmJMhdeBE3blso%3D"
{
    "phone": "37066612345",
    "parameters": {
        "phone_link": "myapp://phone_confirmation/{code}"
    }
}

Confirming user's phone number

Info This feature is not available by default and is enabled only for some clients
This method allows to confirm user's phone number, added when registering user or by assign number request. User gets special code by SMS, which she should input to the client. Client sends this code and thus confirms the phone number for the user.

Request

PUT https://wallet.paysera.com/rest/v1/user/:userId/phone/confirm

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Request body structure

Parameter
Type
Remarks
Description
code
string
required
Code, sent to user's phone

Response data structure

On success API returns user object. See get user information for more info.

Errors

invalid_code (if code is incorrect), rate_limit_exceeded (if current client made too many invalid code attempts in some period of time)

Example request

PUT /rest/v1/user/221/phone/confirm HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="Q1FKNpCN+oh8A7T0s8MZUIevpGb2OigS28PMzg9Xw4E=", ext="body_hash=sc%2BZyvNgEganUAKIuipczDh2Bd7WT3KE78M3tnuFdoU%3D"
{
    "code": "ABCDEF"
}

Assigning email to user

Info This feature is not available by default and is enabled only for some clients
This method allows to assign email to already registered user. Email with confirmation code is sent to provided email, this code should be sent with email confirmation request after user inputs the code to the client.

Request

POST https://wallet.paysera.com/rest/v1/user/:userId/email

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Request body structure

Parameter
Type
Remarks
Description
email
string
required
User's email
parameters
object (see structure below)
optional
Additional parameters for request

Parameters structure

Parameter
Type
Remarks
Description
email_link
string
optional
Custom link to include in the email sent to user. Must include substring {code}, which will be replaced with the confirmation code.

Response data structure

On success API returns user object. See get user information for more info.

Errors

email_already_assigned, not found, rate_limit_exceeded (if current client made too many requests in some period of time)

Example request

POST /rest/v1/user/221/email HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="pRH5X3W30ktJ97vhmOBDJ82O+Jasg1RQ+SlNeYdwD0g=", ext="body_hash=XdfKkp5CnXHijeYwWiGq53BkFzRK98VwDQXi1et8%2BpY%3D"
{
    "email": "test@test.com"
}

Confirming user's email address

Info This feature is not available by default and is enabled only for some clients
This method allows to confirm user's email address, added when registering user. User gets special code by email, which she should input to the client. Client sends this code and thus confirms the email address for the user.

Request

PUT https://wallet.paysera.com/rest/v1/user/:userId/email/confirm

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Request body structure

Parameter
Type
Remarks
Description
code
string
required
Code, sent to user's email address

Response data structure

On success API returns user object. See get user information for more info.

Errors

invalid_code (if code is incorrect), rate_limit_exceeded (if current client made too many invalid code attempts in some period of time)

Example request

PUT /rest/v1/user/221/email/confirm HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="h99hxFpjRKH7m3PK0CKSbKD+4W0d8QhzHZKaF75KvO4=", ext="body_hash=sc%2BZyvNgEganUAKIuipczDh2Bd7WT3KE78M3tnuFdoU%3D"
{
    "code": "ABCDEF"
}

Resetting user's password

Info This feature is not available by default and is enabled only for some clients
These methods allow to reset user's password for Paysera system. To reset a password, these steps must be taken:
  1. Client makes request to API providing user's phone or email address.
  2. If user is identified in Paysera system, error response is returned with code identity_required. In this case client asks user for nationality and person code. Client makes request again, providing user's phone or email address, together with identity information.
  3. Paysera system sends user SMS or email with confirmation code and card information.
  4. User inputs the code and new password into the client.
  5. Client makes password change request, providing confirmation code and new password.

Request

POST https://wallet.paysera.com/rest/v1/user/password/reset

Request body structure

Parameter
Type
Remarks
Description
email
string
required if phone is not specified, unavailable otherwise
Email address of the user
phone
string
required if email is not specified, unavailable otherwise
Phone number of the user. Must start with country code and without 00 or + sign
identity
object (see structure below)
required if user has confirmed identity
Person code
parameters
object (see structure below)
optional
Additional parameters for request

Identity data structure

Parameter
Type
Remarks
Description
code
string
required
Person's identification code

Parameters structure

Parameter
Type
Remarks
Description
phone_link
string
optional
Custom link to include in the SMS sent to user. Must include substring {code}, which will be replaced with the confirmation code. This is intended to provide easier phone confirmation in mobile applications, where links could open and prefill the code to the program or would make instant API call
email_link
string
optional
Custom link to include in the email sent to user. Must include substring {code}, which will be replaced with the confirmation code. This is intended to provide easier email confirmation in mobile applications, where links could open and prefill the code to the program or would make instant API call
Info Parameters can be provided only by clients with type app_client

Response data structure

On success API returns user object. See get user information for more information.

Errors

identity_required (if identity is not provided, but required for resetting the password), invalid_identity (if user identity does not match confirmed one), rate_limit_exceeded (if too many requests or invalid requests are made from this client in specified time period)

Example request

POST /rest/v1/user HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="CaA+7p90dpxasbRdcXQljrPSO4Jfa7NGhLBB2aoEhq0=", ext="body_hash=IwZ%2FnwduvQV8u0dfbkt97V9Cc6GpFq1CTy0v2bcpTdg%3D"
{
    "email": "email@example.com",
    "parameters": {
        "email_link": "myapp://reset_password/{code}"
    }
}

Example request if identity is needed

POST /rest/v1/user HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="hfhgmDsQVFhS8cqY9bPr1B7xm+rWk5/r5/sNCZptFM8=", ext="body_hash=6D98%2BlNEct%2BDRiE48vINf56FiIL%2BKGEklMp%2FAYo3EKg%3D"
{
    "email": "37066612345",
    "identity": {
        "code": "31001010000"
    },
    "parameters": {
        "phone_link": "myapp://reset_password/{code}"
    }
}

Request for resetting the password

PUT https://wallet.paysera.com/rest/v1/user/:userId/password

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Request data structure

Parameter
Type
Remarks
Description
code
string
required if old_password is not specified, unavailable otherwise
Confirmation code sent to user's email or phone
old_password
string
required if code is not specified, unavailable otherwise
Old user password
password
string
required
New password for the user. Currently, password must be at least 8 symbols long

Response data structure

On success API returns user object. See get user information for more information.

Errors

invalid_parameters (if password does not match required constraints), invalid_code (if wrong code was provided), rate_limit_exceeded (if too many requests or invalid requests are made from this client in specified time period) invalid_password (wrong old password was specified)

Example request - reset code specified

PUT /rest/v1/user/221/password HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="pt/524MeyaiUpF9EDN/N7HZG/tP4EgMBhiYX4Fq1sxw=", ext="body_hash=Kvtu30NDTm2TmQwqvn7GVhBIUM1ZsysaQiNCpAWNtBM%3D"
{
    "code": "ABCDEF",
    "password": "newSecurePassword33"
}

Example request - old password specified

PUT /rest/v1/user/221/password HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="1DYxLJwbdRZUqllOdAo3iCXG3ertrPABlOreZl0h1eg=", ext="body_hash=bqHO7kRJIqbt14UYtHiqn%2FKLlmM3Ck2%2FyI35WciaaEE%3D"
{
    "old_password": "myOldPassword",
    "password": "newSecurePassword33"
}

Providing user's identity

Info This feature is not available by default and is enabled only for some clients
This method allows to provide additional information about already registered user. This is only available for offline or gateway clients. Receipt must be printed and given to the user after this request. User will get information to the provided phone or email and on receipt, how she can confirm the information online.

Request

PUT https://wallet.paysera.com/rest/v1/user/:id

Parameters

id - id of the user. Can be integer or me (if access token is used)

Request body structure

Parameter
Type
Remarks
Description
email
string
required if phone is not specified
Email address of the user
phone
string
required if email is not specified
Phone number of the user. Must start with country code and without 00 or + sign
identity
object (see structure in Register new user)
required
Name, surname and personal code of the user

Response data structure

On success API returns user object. See get user information for more info.

Errors

person_code_already_assigned, email_already_assigned, phone_already_assigned, person_code_mismatch, not_found

Example request

PUT /rest/v1/user/221 HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="c/xYJqipUXpIvRHe9I4bxMyjPdLdrDhI6QnvIYipXy8=", ext="body_hash=dw6npD8qCjzeCskm3%2B5HKXePepCH1%2Bgv9%2FrjzVNvrw4%3D"
{
    "phone": "37066612345",
    "identity": {
        "name": "John",
        "surname": "Smith",
        "nationality": "lt",
        "code": "31001010000"
    }
}

Getting receipt for identified user

In case user is identified at some location (for offline or gateway clients), user receipt can (and must) be printed and given to the user. It is not allowed for the client to save receipt's text or display it for anyone else except the user herself.

Identification receipt request

GET https://wallet.paysera.com/rest/v1/user/:userId/receipt/identification?locale=:locale&width=:width

Parameters

userId - id of the user. Can be integer or me (if access token is used)

locale - optional parameter; locale for the text translation. Currently available locales: en, lt, ru

width - optional parameter; maximum symbol count in one line. Longer lines will be broken into separate ones

Response data structure

Parameter
Type
Remarks
Description
text
string
always
Text for the customer. New lines are separated by \r\n characters (CR + LF)

Example request

GET /rest/v1/user/221/receipt/identification?locale=en HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="OKROveAfjh3RLp0YrBov/OtaYjVXD6aJTiLCCNMe+Cw="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "text": "You have started identification process in Paysera systemrnYour confirmation code is ABCDEF"
}

Sending user's document

Info This feature is not available by default and is enabled only for some clients
These methods allow sending scanned document of registered or identified user and it's information.

Document upload request

POST https://wallet.paysera.com/rest/v1/user/:userId/document

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Request body

Request body is binary content of the file being uploaded - no other formatting takes place.

Response data structure

Response is an object with single key - id. This is document's ID, which is provided when giving document's metadata.

Example response

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

Document metadata request

PUT https://wallet.paysera.com/rest/v1/user/document/:documentId/metadata

Parameters

documentId - id of the document, given in the response when document was uploaded

Request body structure

Parameter
Type
Remarks
Description
title
string
required
Title for the document in free form text
extension
string
required
Extension for the file uploaded. For example: pdf, jpg
type
string
required
Type of the document. One of these values: card, passport, driver_licence
number
string
required
Number of the document (identifier), as displayed on the document itself
date
string
optional
Date when document was issued. Must be in format yyyy-mm-dd, for example 1983-01-29

Response data structure

Response has same keys as was provided in request, with additional id parameter - ID of the document.

Errors

not_found, invalid_state (if document metadata was already provided)

Example request

PUT /rest/v1/user/document/1232 HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="2yVI5P5MbpJwk0rz8Lm09aU2hhDNQV022/JxEdRByP0=", ext="body_hash=RJBemF0EHy9gZzn7Ctf1%2FeDi3ptSrdPSz%2FS3hWtdTU4%3D"
{
    "title": "Scanned driver's licence for John Smith",
    "extension": "pdf",
    "type": "driver_licence",
    "number": "BV1221312413",
    "date": "2010-04-30"
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 1232,
    "title": "Scanned driver's licence for John Smith",
    "extension": "pdf",
    "type": "driver_licence",
    "number": "BV1221312413",
    "date": "2010-04-30"
}

Get users' positions

This method returns information about current positions of Paysera users. This method requires special client privileges.
Info This feature is not available by default and is enabled only for some clients

Requesting positions in some specific place

GET https://wallet.paysera.com/rest/v1/positions?lat=lat&lng=lng&distance=distance&limit=:limit&offset=:offset

Locations are filtered by place, providing lat, lng and distance parameters.

Parameters

lat - required; latitude of coordinates in decimal format

lng - required; longitude of coordinates in decimal format

distance - optional; distance in meters from given coordinates for filtering, defaults to 500

limit - optional; maximum number of positions to be returned in one response. Defaults to 20, maximum available is 200.

offset - optional; number of statements to skip. Defaults to 0

Response data structure

Parameter
Type
Remarks
Description
positions
array of objects
always
Each item in array is position object, which is detalized bellow
_metadata
object
always
Additional information about result

Position data structure

Parameter
Type
Remarks
Description
distance
integer
always
Distance for this user from given coordinates
user_info
object
always
Information about the user. See structure below
User info data structure
Parameter
Type
Remarks
Description
wallet_id
integer
always
ID of user's main wallet
account_number
string
always
User's main account number, related to the main wallet
user_id
integer
always
ID of this user
display_name
string
optional
Full name (possibly only with the first letter of surname) or title of the user
phone
string
optional
Phone number of the user
email
string
optional
Email address of the user
Info Usually phone or email is only provided when display_name is unavailable.

Metadata information structure

Parameter
Type
Remarks
Description
total
integer
always
Total count of results, ignoring limit and offset parameters
offset
integer
always
Used offset - how many results from the beginning were skipped
limit
integer
always
Used limit - maximum count of available results in single response

Example request

GET /rest/v1/positions?lat=54.698686&lng=25.216615&distance=2000&limit=50 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="9Y/yxkeNyfjO9pZEsV1xGUTJOJgrIooCEYYLZIpBqO8="
Info In this example we are requesting positions in 2km distance from N54° 41.9212', E025° 12.9969', limiting result to 50.

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "locations": [
        {
            "distance": 15,
            "user_info": {
                "display_name": "John S.",
                "user_id": 54,
                "wallet_id": 4558,
                "account_number": "EVP7010001000101"
            }
        },
        {
            "distance": 298,
            "user_info": {
                "display_name": "Peter J.",
                "user_id": 4457,
                "wallet_id": 25487,
                "account_number": "EVP6310001000103"
            }
        }
    ],
    "_metadata": {
        "total": 2,
        "offset": 0,
        "limit": 50
    }
}

Manage user's position

These methods allow to provide, get or remove user's position for others to find by API. To use these methods user_position scope is required.

Info This feature is not available by default and is enabled only for some clients

Providing user's position

PUT https://wallet.paysera.com/rest/v1/user/:userId/position

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Request body structure

Request body contains user's position data structure.

Parameter
Type
Remarks
Description
lat
float
required
Latitude coordinate of user's current position
lng
float
required
Longitude coordinate of user's current position
type
string
optional
If not passed, location is registered as broadcasted position and can be found publicly. Available values: hidden (not displayed in public search), merchant (not displayed in public search, used for mobile retailers)

Response data structure

On success API returns user's position object - it has the same structure like one passed in request.

Getting current user's position

GET https://wallet.paysera.com/rest/v1/user/:userId/position

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Response data structure

On success API returns user's position object.

Removing current user's position

DELETE https://wallet.paysera.com/rest/v1/user/:userId/position

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Response data structure

On success API returns user's position object.

User's avatar

Displaying user's avatar

To display user's avatar, no API method is required - simple GET request to provided URL is enough without any authentication. 

GET https://www.paysera.com/avatar/:userId.jpg?size=:size&default=:default

Parameters

userId - id of the user. Can be integer or me (if access token is used)

size - optional; size of the avatar in pixels, defaults to 200

default - optional; mm to display default image, 404 to return status code 404; defaults to 404

Providing and removing user's avatar

These methods allows to provide and remove user's avatar. To use these methods avatar scope is required.

Info This feature is not available by default and is enabled only for some clients

Providing user's avatar

PUT https://wallet.paysera.com/rest/v1/user/:userId/avatar

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Request body structure

Request body is binary content of the image.

Warning Image content is not JSON encoded, it's posted as the body itself.

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of the user

Removing user's avatar

DELETE https://wallet.paysera.com/rest/v1/user/:userId/avatar

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of the user

Contact book

Contact book is resource for helping to search for contacts. It can be used both to search for wallets by contacts and to subscribe to push notifications when user registers with such contact. If only one-time search is needed, the same can be achieved with simple wallet batch search.

Creating contact book

POST https://wallet.paysera.com/rest/v1/user/:userId/contact-book

Parameters

userId - id of the user. Can be integer or me (if access token is used)

Request body structure

Parameter
Type
Remarks
Description
emails
array of strings
optional
Array of emails
phones
array of strings
optional
Array of phone numbers; each phone must start with country code without 00 or + sign and contain only digits
email_hashes
array of strings
optional
Array of SHA1 email hashes; each email address must be lower-cased before hashing. SHA1 result must be in hex format
phone_hashes
array of strings
optional
Array of SHA1 phone hashes; each phone must start with country code without 00 or + sign and contain only digits before hashing. SHA1 result must be in hex format

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of the contact book

Deleting contact book

DELETE https://wallet.paysera.com/rest/v1/contact-book/:contactBookId

Parameters

contactBookId - Contact book identifier

Example response

HTTP/1.1 204 No Content
Content-type: text/html;charset=utf-8
{
    "time": 1383116734
}

Deleting contacts from contact book

DELETE https://wallet.paysera.com/rest/v1/contact-book/:contactBookId/contacts?email=:email&phone=:phone&email_hash=:email_hash&phone_hash=:phone_hash

Parameters

Parameters are passed in the query string.

Example request

DELETE /rest/v1/contact-book/1/contacts?email=a@evp.lt,b@evp.lt&phone=37012312345 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="v8d2hRotPUCDdGP6hoXqYQZyolfpARS45PPBzNi4PPg="
Parameter
Type
Remarks
Description
contactBookId
string
required
Contact book identifier
email
string
optional
Comma seperated email list
phone
string
optional
Comma seperated phone list
email_hash
string
optional
Comma seperated email hash list
phone_hash
string
optional
Comma seperated phone hash list

Example response

HTTP/1.1 204 No Content
Content-type: text/html;charset=utf-8
{
    "time": 1383116734
}

Appending contacts to contact book

PUT https://wallet.paysera.com/rest/v1/contact-book/:id/append

Parameters

id - ID of the contact book to append contacts to

Request body structure

Request structure is the same as when creating new contact book.

Response data structure

Response structure is the same as when creating new contact book. Only wallets for appended contacts are returned.

User services

Resource allows to get User services and enable specific ones. You must have scope services to access this resource.

Get User services

GET https://wallet.paysera.com/rest/v1/user/:userId/services

Enable User service

PUT https://wallet.paysera.com/rest/v1/user/:userId/service/:service

Parameters

userId - id of the user.

service - service identifier. String

Response data structure

Parameter
Type
Remarks
Description
user_id
integer
always
User ID
services
array
always
Array of Service objects

Service structure

Parameter
Type
Remarks
Description
service
string
always
Service identifier
status
string
always
one of enabled or disabled
title
string
always
Service title
actions
array
always
array of action names that can be performed on this Service, usually enable and disable
dependencies
array
always
array of dependencies as strings for this Service to enable
url
string
optional
Service description in HTML
url_plain
string
optional
Service description in Plain text
added
integer
optional
Timestamp when this service was added to User