Making client related calls

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

About

This method returns project by ID. Client can get information about any project that can be acecssed 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

About

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

About

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
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": "M\u0117nulio g. 7, Vilnius, Lietuva",
            "lat": 54.668516,
            "lng": 25.235055,
            "radius": 20,
            "prices": [
                {
                    "title": "Cash-in",
                    "type": "price",
                    "price": {
                        "amount": 100,
                        "currency": "EUR"
                    }
                },
                {
                    "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

About

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

About

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

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

About

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"
    }
}