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 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="TbiHzbRPMInPuR+QSD18wbU3z/23WdgKhzNU1rasdek="
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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="GNZmjRCVYQKrc/KxSoN9npyACzPKKnGQ5Nr0XD1xIUc="
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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="b4BFRzuCa8cqxOm2VSSTJ5a1vdJfe1ri/7vLkFlovwA="
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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="q2vCVtthKq3V2Y4v59KpGIHVSu12OELwxLyjBzqew1I="
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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="7/AHgWQF/ibko7klj7XQg9GAjJ0cLMy9jTUGn40XSKI="
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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="u8nWmx1+KVY8yTyvdxiAZT1j9hgqH1G1aCQhUhsIzUE=", 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"
}
}