Atsiprašome, kol kas šios programinės sąsajos specifikacija galima tik anglų kalba.

User resource

Get user information

About

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

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 levels (see Levels compare) list with their description are provided below.

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

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="0l66VCfYACFkDc/rUkJrupfGjThJ8GOqFHYvdAYT8zI="
InfoIn 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"
    }
}

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

GET https://wallet.paysera.com/rest/v1/user/:id/email
GET https://wallet.paysera.com/rest/v1/user/:id/phone
GET https://wallet.paysera.com/rest/v1/user/:id/address
GET https://wallet.paysera.com/rest/v1/user/:id/identity
GET https://wallet.paysera.com/rest/v1/user/:id/wallets
Parameters
id
id of the user. Can be integer or me (if access token is used)

Example request

GET /rest/v1/user/221/identity HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="y3Ez14+wmObGH+dPxtn3LJfFQJV7hK5RR9c6uJ6RGm0="
InfoIn this example we are requesting the identity information of user which ID is 221

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "name": "John",
    "surname": "Smith",
    "nationality": "lt",
    "code": "31001010000"
}

Example request for user's 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="CDBIwvWBtshk9yIRWbrDnZz+/NZKD5qW29Ffnm5IjII="
InfoIn this example we are requesting available wallets for user which ID is 221

Example response for user's wallets

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
macro
micro
offline
payment_instruments
paysera_app
sms_bank

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="PKA+3GxVh0X2+8DVuxX7igzatoBPvOdMcD8e9uouk3I="
InfoIn 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="RNIanUd4WEGu2a9ZZYa7R4ebfmTD+ssfwipSCOQ8ye8="
InfoIn 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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="nUYxG4rxBqbANt2WiMxe6BU71R9+oJQ/OyuafZfutTg=", 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="P760aLJ1M/yW3qhUoa1G3ouyekQu4+MQYVFLEHExnHY=", 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="ekXXgm4+b/r3LOCCBroBrXfAjU8UTxhB3kAliMKqMxM=", 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="kClFCuMN1BRiovEkODNsW/8vREGi/sjwR9SEGyy5//k="

Example response

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

Assigning phone to user

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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="AULO+AsShM/hgWUFapzYHbHNu0ug5zZdTC654BACFEc=", 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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="D+xZBCy4+gWP+6Jyd2UEKk6uDzZpgL2AgMDEiaBCw7Q=", 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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="ikzZmDQqwhr0uUTVdNHudv1efiDxTA/lTn8hP9IUZUw=", 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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="cldTYQZ136J+EhjH9wpCMTSZrGQW5oCjJEnJBItbDM0=", 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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="a5mN8fGjRnG97bcwFJwL6DkJVd/61tAe5QTi0D1ikWM=", 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="GQ7cgvH3IMXp+shEWEbVHL5QXiD8QJ2UbQKgxJlEh2M=", 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="+dgpTf1nHgNSqZAzXcMnSXGOuwXbd4pyV744mS4XiwQ=", 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="C+a/rYDytZPybx0ZSXGVNd0xBb9GeKjJDQcx/bUtjVo=", 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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="1hUO35uGbXNrRGJC+rMlOIpBRvQpdEmVFIt9pYRtzXk=", 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="KhQFCGA65s60Ucl+oQJrJU6Zr7PmN0BQgwHRK0n/yHU="

Example response

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

Sending user's document

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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="dpE41kiwVgPefFOn7jSOW+Im9Rif2BWVsaOMwTfjGFA=", 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

About

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 statements 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="+gJwjV+1yISdMvmFiX1WuVYuZP0LqBeZwCiCEBndqVQ="
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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="rEjICHhinb2IyKK7XmkUWadgX95iTdTYaN+kRuAu8V0="
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