English

Clients, Projects, Locations

This chapter describes methods to be used to get information and manage API clients, projects and locations.

Following resources are described here: Client, Project, Location.

Project resource

Get project by ID

This method returns project by ID. Client can get information about any project that can be accessed otherwise with current access token or without it. Special permissions are needed for the client to access this method for any project.

Request

GET https://wallet.paysera.com/rest/v1/project/:projectId

Parameters

projectId - ID of the project

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of this project
title
string
always
Title of this project
description
string
only if available
Description for this project
wallet_id
integer
only if available
ID of the wallet related to this project
owner_display_name
string
only if available
Display name for the owner of this project

Example request

GET /rest/v1/user/project/1221 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="IBdXGqAKU5ixET6qRtUoB2ZT5ETyt2f6BuOVsu/pCQg="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 1221,
    "title": "Project's title",
    "description": "Description for this project",
    "wallet_id": 2112,
    "owner_display_name": "Some company"
}

Get user's administered projects

This method returns projects that can be administered by the user. Scope projects is needed for this method.

Request

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

Parameters

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

Response data structure

Response is array of objects, which structure is the same as when getting project by ID.

Example request

GET /rest/v1/user/me/projects HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="tS6cJNbG6eSZ8q+sZ0JdUR/mF5Zfvujc1qchXJVFs08="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
[
    {
        "id": 1221,
        "title": "Project's title",
        "description": "Description for this project",
        "wallet_id": 2112,
        "owner_display_name": "Some company"
    }
]

Location resource

Get all available locations

This method returns information about all locations, where Paysera account can be used. Each location represents some specific place with address and usually GPS coordinates.

Request

GET https://wallet.paysera.com/rest/v1/locations?locale=locale&lat=lat&lng=lng&distance=distance&updated_after=updated_after&status=status&limit=:limit&offset=:offset

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

Parameters

locale - recommended; locale for translations of location descriptions

lat - optional; latitude of coordinates in decimal format. Can be provided only with lng

lng - optional; longitude of coordinates in decimal format. Can be provided only with lat

distance - optional; distance in meters from given coordinates for filtering. Can be provided only with lat and lng, defaults to 500

updated_after - optional; UNIX timestamp for filtering locations by last edit date. Can be used to periodically synchronize location list

status - optional, defaults to active; statuses for locations, can be separated by comma, for example active,inactive. Can be used to synchronize locations that were inactivated

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
locations
array of objects
always
Each item in array is location object, which is detalized bellow
_metadata
object
always
Additional information about result

Location data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of this location
project_id
integer
always
ID of the project that this location belongs to
title
string
always
Title for this location
updated_at
integer
always
UNIX timestamp of date the location was added or edited
status
string
always
One of the following: active, inactive. Inactive locations are ones that are no longer available
description
string
optional
Description for this location, if provided
address
string
optional
Address for this location, if provided
lat
float
optional
Latitude of coordinates for this location, if provided. Comes together with lng
lng
float
optional
Longitude of coordinates for this location, if provided. Comes together with lat
radius
integer
optional
Radius of this location in meters. Comes together with lng and lat
prices
array of object
optional
Current prices for Paysera related services, see structure below
working_hours
object
optional
Working hours for this location, see structure below
services
object
optional
Available services in this location, related to Paysera account. See structure below
images
object
always
Object with two elements: pin_open and pin_closed. Each of them contains string - full URL to image for the map
remote_orders
object
optional
Object with an element spot_id. Only available if Spot is related to Location.
Price data structure
Parameter
Type
Remarks
Description
type
string
always
One of the following: price, offer
title
string
always
Description of service or special offer
price
object
optional
Only if type is price

Structure for price object is detailed below.

Parameter
Type
Remarks
Description
amount
integer
always
Price amount in cents
currency
string
always
Price currency
amount_decimal
string
always
Price decimal amount
Working hours data structure

Keys in this object defines day of the week, each object for these keys have the same structure, which is detailed below. Available keys: monday, tuesday, wednesday, thursday, friday, saturday, sunday. Some of the keys can be missing, which means that location is not working at that day. Closing time can be smaller that opening time if location closes at the next night of specified weekday.

Parameter
Type
Remarks
Description
opening_time
string
always
Opening time in format hh:mm
closing_time
string
always
Closing time in format hh:mm
Services data structure
Parameter
Type
Remarks
Description
cash_in
object
optional
Information about cash-in service. Can be omitted if unavailable
cash_out
object
optional
Information about cash-out service. Can be omitted if unavailable
identification
object
optional
Information about identification service. Can be omitted if unavailable
pay
object
optional
Information about ability to pay with Paysera account. Can be omitted if unavailable

Structure for each service element is detailed below.

Parameter
Type
Remarks
Description
available
boolean
always
Whether this service is available at this location
categories
array of integer
optional, available only if service is pay
List of category IDs for this location. See location categories for more details
types
array of strings
optional, available only if service is cash_in or cash_out
List of supported Cash In or Cash Out types. See available types below for more details

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

Available Cash In types

contact - Cash in available with contact information (email, phone, etc.)

bar_code - Cash in available with multi-use BAR code

document - Cash in available with identification document

one_time_bar_code - Cash in available with single-use BAR code

Available Cash Out types

qr_code - Cash out available with QR code

document - Cash out available with identification document

Example request

GET /rest/v1/locations?locale=en&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="O0cJ+Txl/jbh4gKE6UhMWPkjZwZ4tKF22+vOiSO4Gl4="
Info In this example we are requesting locations in 2km distance from N54° 41.9212', E025° 12.9969', limiting result to 50. Result will contain location descriptions in English, if available.

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "locations": [
        {
            "id": 48,
            "title": "EVP International",
            "updated_at": 1382969469,
            "status": "active",
            "description": "Place to cash-in or cash-out from Paysera account",
            "address": "Mu0117nulio g. 7, Vilnius, Lietuva",
            "lat": 54.668516,
            "lng": 25.235055,
            "radius": 20,
            "prices": [
                {
                    "title": "Cash-in",
                    "type": "price",
                    "price": {
                        "amount": 100,
                        "currency": "EUR",
                        "amount_decimal": "1.00"
                    }
                },
                {
                    "title": "Cash-out is for free!",
                    "type": "offer"
                }
            ],
            "working_hours": {
                "monday": {
                    "from": "08:00",
                    "to": "20:00"
                },
                "tuesday": {
                    "from": "08:00",
                    "to": "20:00"
                },
                "wednesday": {
                    "from": "08:00",
                    "to": "20:00"
                },
                "thursday": {
                    "from": "08:00",
                    "to": "20:00"
                },
                "friday": {
                    "from": "08:00",
                    "to": "18:00"
                }
            },
            "services": {
                "pay": {
                    "available": true,
                    "categories": [
                        1
                    ]
                },
                "cash_in": {
                    "available": true,
                    "types": [
                        "contact",
                        "document"
                    ]
                }
            },
            "images": {
                "pin_open": "https://wallet.paysera.com/assets/locations/pin/o_empty.png",
                "pin_closed": "https://wallet.paysera.com/assets/locations/pin/c_empty.png"
            },
            "remote_orders": {
                "spot_id": 2
            }
        }
    ],
    "_metadata": {
        "total": 1,
        "offset": 0,
        "limit": 50
    }
}

Location category resource

Get all available location categories

This method returns information about all location categories. Each location can be assigned to one or more categories, if pay service is available at this location.

Request

GET https://wallet.paysera.com/rest/v1/locations/pay-categories?locale=locale

Parameters

locale - recommended; locale for translations of location descriptions

Response data structure

Response is array of location category objects. Structure for each object is provided below.

Parameter
Type
Remarks
Description
id
integer
always
ID for this category
title
string
always
Title of this category
parent_id
integer
optional
ID of parent category. If this item is not provided, this category is one of main categories
images
object (see structure below)
optional
URIs for images for this category

Images data structure

Parameter
Type
Remarks
Description
active_uri
string
always
URI to image for active category
inactive_uri
string
always
URI to image for inactive category

Example request

GET /rest/v1/locations/pay-categories?locale=en HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="6Mdu6MiB9O2TpZ34rwnZE330EOKW2cp90kI7Mz/tnL8="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
[
    {
        "id": 1,
        "title": "Entertainment"
    },
    {
        "id": 2,
        "title": "Bowling",
        "parent_id": 1,
        "images": {
            "active_uri": "https://wallet.paysera.com/assets/locations/pay_category/bowling.png",
            "inactive_uri": "https://wallet.paysera.com/assets/locations/pay_category/bowling_off.png"
        }
    },
    {
        "id": 3,
        "title": "Movie Theater",
        "parent_id": 1
    },
    {
        "id": 4,
        "title": "Restaurant"
    }
]

Client resource

Get current client information

This method returns information about current API client. This can be used for checking client permissions, getting project's configured title or for testing your client (signing, making requests etc.)

Request

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

Response data structure

Parameter
Type
Remarks
Description
title
string
always
Configured title of the project, related to current API client
permissions
array of string
always
Array of permission identifiers. See below for available permissions
type
string
always
Type of current client. Available values: private_client, application, app_client
credentials
object
Only in response to client registration request
Credentials to use for created client
info
object
Only if available
The same as provided when registering client

Available permissions

show_in_frame - Whether confirmation page can be viewed inside a frame in website, associated with current client

give_trusted_user_info - Whether user's information given from current client is trusted

accept_with_flash - Whether current client can accept transactions sending FLASH SMS

accept_with_pin - Whether current client can accept transactions sending user's PIN code

Example request

GET /rest/v1/client HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="ecDUTRKrXLlLqDLVypJfqAzQX80qDlCk+OLGCH9LmPM="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "title": "Project's title",
    "permissions": [
        "show_in_frame",
        "accept_with_flash"
    ],
    "type": "private_client"
}

Create new client

This method is available only for application clients. When application in some device is ran for the first time, new client must be created using this API method. After creation, all other requests to API must be made with created client's credentials.

Request

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

Request body structure

Parameter
Type
Remarks
Description
type
string
required
Currently only app_client is available
info
object
required
See structure below

Info data structure

Parameter
Type
Remarks
Description
title
string
optional
Description of phone, if available
os
string
recommended
Operating system of the phone
model
string
recommended
Model of the phone
imei
string
optional
IMEI number of the phone
device_id
string
recommended
Unique identificator for this device

Response data structure

The same as when getting client's information. credentials key is available in the response for this request.

Structure of credentials item

Parameter
Type
Remarks
Description
access_token
string
always
Configured title of the project, related to current API client
token_type
string
always
Currently only one value is available - mac
mac_key
string
If token_type is mac
Secret key to sign requests with. This value must be kept secret
mac_algorithm
string
If token_type is mac
Currently only one value is available - hmac-sha-256

Example request

POST /rest/v1/client 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="fXIXiMYcWAYOUdJlP9HYMF+MWlj46YJGu71VzE1i1B0=", ext="body_hash=o4TvudjujyH2YNBztns%2BYbGTCSqSs9HubjzybIVTqsE%3D"
{
    "type": "app_client",
    "info": {
        "title": "My main phone",
        "os": "Android 4.2.2",
        "model": "Samsung GT-I9105P",
        "imei": "490154203237518",
        "device_id": "11651f8c82017a6df931b4b53d9198cc"
    }
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "title": "Project's title",
    "permissions": [
        "password_grant",
        "accept_with_pin"
    ],
    "type": "app_client",
    "info": {
        "title": "My main phone",
        "os": "Android 4.2.2",
        "model": "Samsung GT-I9105P",
        "imei": "490154203237518",
        "device_id": "11651f8c82017a6df931b4b53d9198cc"
    },
    "credentials": {
        "access_token": "1iGYMlmRJXsxnXmr",
        "token_type": "mac",
        "mac_key": "lwn46MtHtHbQJU0aMUIK5vsiohVS1Llj",
        "mac_algorithm": "hmac-sha-256"
    }
}

Client permissions related to wallets resource

Get client permissions to wallets

This endpoint returns a list of wallets with their details and scopes. This can be used for checking permissions which client wallets already have and updating permissions to each wallet (set and unset balance and statements permissions)

Request

GET https://wallet.paysera.com/rest/v1/client/{clientId}/permissions-to-wallets

Response data structure

The response is an array of objects, each representing a wallet and its associated scopes.

Parameter
Type
Remarks
Description
id
integer
always
The unique identifier of the wallet
owner
integer
always
The user ID of the wallet's owner
account
object
always
The account information associated with the wallet. See structure below
scopes
array
This array may be empty
An array of scopes associated with the wallet

Structure of account item

Parameter
Type
Remarks
Description
number
string
always
The account number
user_id
integer
always
The user ID associated with the account
owner_type
string
always
The type of the account owner. Available values: legal, natural

Example request

GET /rest/v1/client/1234/permissions-to-wallets HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="eTZx70MnxXPPoxnzUWHl/p17KMHdjW6gCfzLSwKWmpU="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
[
    {
        "wallet": {
            "id": 1,
            "owner": 1234,
            "account": {
                "number": "EVP1",
                "user_id": 1234,
                "owner_type": "natural"
            }
        },
        "scopes": [
            "balance",
            "statements"
        ]
    },
    {
        "wallet": {
            "id": 2,
            "owner": 1234,
            "account": {
                "number": "EVP2",
                "user_id": 1234,
                "owner_type": "natural"
            }
        },
        "scopes": [
            "balance"
        ]
    },
    {
        "wallet": {
            "id": 3,
            "owner": 1234,
            "account": {
                "number": "EVP3",
                "user_id": 1234,
                "owner_type": "natural"
            }
        },
        "scopes": []
    }
]

Update client permissions to wallets

This method is available only for private clients.

Request

PUT https://wallet.paysera.com/rest/v1/client/{clientId}

Request body structure

Parameter
Type
Remarks
Description
type
string
required
Currently only app_client, private_client is available
permissions
array
This array may be empty
An array of client permissions. If empty all granted permissions will be revoked
project_id
integer
optional
ID of project asociated with client
location_id
integer
optional
ID of location asociated with client
service_agreement_id
integer
optional
hosts
array
optional
See structure below
permissions_to_wallets
array
optional
See structure below
info
object
optional
See structure below

Available permissions

show_in_frame - Whether confirmation page can be viewed inside a frame in website, associated with current client

use_password_grant - Whether current client can use password grant type

accept_with_flash - Whether current client can accept transactions sending FLASH SMS

accept_with_pin - Whether current client can accept transactions sending user's PIN code

access_statements - Whether client has access to statements

search_by_person_code - Whether client can search by person code

client_make_bank_transfers - Whether client can make bank transfers

Available scopes of permissions to wallets

balance - Whether user has access to balance

statements - Whether user has access to statements

Host data structure

Parameter
Type
Remarks
Description
host
string
always
Host
port
integer
Can be null
Port
path
string
Can be empty
Path
protocol
string
always
Protocol
any_port
bool
always
any_subdomain
bool
always

Permission to wallet data structure

Parameter
Type
Remarks
Description
wallet_id
integer
required
Related wallet ID
account_number
string
required
Related account number
scopes
array
Array of strings. Currently only balance, statements is available
Scope of permissions which should be applied to specified wallet

Info data structure

Parameter
Type
Remarks
Description
title
string
optional
Description of phone, if available
os
string
recommended
Operating system of the phone
model
string
recommended
Model of the phone
imei
string
optional
IMEI number of the phone
device_id
string
recommended
Unique identificator for this device

Response data structure

The same as when getting client's information.

Structure of host item

Parameter
Type
Remarks
Description
host
string
always
Host
port
integer
Can be null
Port
path
string
Can be empty
Path
protocol
string
always
Protocol
any_port
bool
always
any_subdomain
bool
always

Structure of project item

Parameter
Type
Remarks
Description
id
integer
always
Project ID
title
String
Can be empty
Project title
description
string
Can be empty
Project description
wallet_id
integer
always
ID of related wallet

Example request

PUT /rest/v1/client/{clientId} 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="H/Zxvdh7fWaQ00s61PZfoOYDGwf3rO1KJ0XuZFo65pQ=", ext="body_hash=O24TGvmcW9KukA8Qxwf%2Frvju3mXEqxpFsmyHMou572g%3D"
{
    "type": "private_client",
    "permissions": [
        "show_in_frame",
        "use_password_grant"
    ],
    "project_id": 123,
    "hosts": [
        {
            "host": "example.com",
            "port": null,
            "path": "/some-path",
            "protocol": "https",
            "any_port": true,
            "any_subdomain": true
        }
    ],
    "id": 1234,
    "title": "",
    "permissions_to_wallets": [
        {
            "wallet_id": 1,
            "account_number": "EVP1",
            "scopes": [
                "balance",
                "statement"
            ]
        },
        {
            "wallet_id": 2,
            "account_number": "EVP2",
            "scopes": [
                "balance"
            ]
        }
    ]
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 1234,
    "title": "",
    "permissions": [
        "use_oauth_api",
        "use_wallet_api",
        "use_client_api",
        "use_offline_scopes",
        "use_code_grant",
        "show_in_frame",
        "use_password_grant"
    ],
    "type": "private_client",
    "hosts": [
        {
            "host": "example.com",
            "port": null,
            "path": "/some-path",
            "protocol": "https",
            "any_port": true,
            "any_subdomain": true
        }
    ],
    "project": {
        "id": 123,
        "title": "",
        "description": "",
        "wallet_id": 1
    }
}