English

POS Features

This chapter describes POS (point of sale) features integration. POS features allow to accept orders in so called spots, that are assigned to locations. One location may have one or more spots.

Two types of API clients should be considered when integrating: clients representing user (typically API client of type app_client) and clients representing merchants, i.e. coffee shop, gas station, etc.

Integration for clients representing user

All requests for clients, representing user, must be made using access token to work.

Common action flow from client is as follows:

  • User arrives, selects free spot and scans spot QR code by using mobile app or retrieves it from other kinds of media.
  • Client receives spot by spot code and uses its ID for all subsequent requests.
  • User may check-in or check-out to/from spot. Spot status becomes waiting after client makes check-in request.
  • Client periodically issues requests for spot by id to get its status and associated orders. Spot may be closed and orders modified by merchant at any time.
  • Client may periodically issue requests to get specific order to track its status and associated transaction changes.
  • Client reserves money for transaction, associated with spot order, using any of standard available ways.
  • Client may periodically issue requests to get transaction status. Order is fully paid only when transaction status is confirmed, that is, merchant software has confirmed that reserved transaction is correct at that particular moment.

Getting spot

This method returns spot. Spot can be requested by spot code or by ID.

Request

By spot code: 
GET https://wallet.paysera.com/rest/v1/spot?code=:code
By spot ID: 
GET https://wallet.paysera.com/rest/v1/spot/:id

Parameters in case of code

code
code that identifies spot; usually full string that was read in QR code

Example requests

By code: 
GET /rest/v1/spot?code=PAYSERA*3%3ATABLE1 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="Fq2JdkPxXggdNUjjhMuMXD6TNxwyTC8bkG3bJGIx3L4="
By ID: 
GET /rest/v1/spot/1 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="BrESuxFsVum5GlD3Wt+IRZP9mMDDDSqP87EPy17ymD4="

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of spot
status
string
always
Status of spot. One of: closed, waiting, opened
identifier
string
only if requested by client that is owner of this spot
Spot identifier, used for identifying spot in the specific location
place_info
object
always
Additional spot details
orders
array of objects
only if client is checked-in in this spot and spot has any orders
Spot orders. Only orders for the current spot session are listed

Place info data structure

Parameter
Type
Remarks
Description
title
string
always
Title of this location
description
string
only if available
Description for this spot
address
string
only if available
Address of this location
logo_uri
string
only if available
URI of logo for this location
location_id
integer
only if available
ID of this location

Order data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of order
transaction_key
string
always
Key of transaction that is associated with this order
status
string
always
Status of order. One of: pending, reserved, confirmed, closed

Meaning of order status codes:

pending
Order is waiting for being paid
reserved
Transaction, related to current order, has status reserved. Confirmation from merchant is pending to finalize payment
confirmed
Transaction has been confirmed by merchant - payment has been successfully made
closed
Order has been closed - it was canceled or paid by other means

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 1,
    "status": "open",
    "identifier": "table1",
    "place_info": {
        "title": "Cool caffe",
        "description": "Coffee and cakes for everyone, even you!",
        "address": "address"
    },
    "orders": [
        {
            "id": 52,
            "transaction_key": "Pu5CPePCkm3TJPlkctcshzkIlxeLU3WR",
            "status": "pending"
        },
        {
            "id": 53,
            "transaction_key": "2jStyeyh7zGQa9Q0dD6TOsEM04JPrWMO",
            "status": "pending"
        }
    ]
}

Checking-in

After checking-in to a closed spot, it's status becomes waiting. One client can be checked-in only in one spot - checking-in in another automatically checks-out of the first one. However, check-out should be always made if available when user leaves the place.

Request

PUT https://wallet.paysera.com/rest/v1/spot/:id/check-in

Example request

PUT /rest/v1/spot/1/check-in HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="3C/sxDllC+4px0UdbtEtTavCqB6Er8lZbIkKtWlQ92U="

Response data structure

Spot data structure is returned.

Checking-out

After checking-out, in case there are no other clients' check-ins, spot status becomes closed.

Request

PUT https://wallet.paysera.com/rest/v1/spot/:id/check-out

Example request

PUT /rest/v1/spot/1/check-out HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="owzKcU4miyJ8H43dm9m2PF9FoofWSJxF6bKBeIP43yY="

Response data structure

Spot data structure is returned.

Getting order

Method gets order by its ID.

Request

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

Example request

GET /rest/v1/order/52 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="bczsUDRIYRfi159d7eRH1NirKdVGbdkH8wn/mwyH4g0="

Response data structure

Order data structure is returned.

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 52,
    "transaction_key": "Pu5CPePCkm3TJPlkcbcshzkIlxeLU3WR",
    "status": "pending"
}

Integration for clients representing merchants

Common action flow for client is as follows:

  • Periodically gets spots with type waiting. If found, it means there are checked-in and waiting clients in those spots.
  • Creates, edits, deletes orders in spots as needed. Corresponding transaction(s) are created when modifying order. After first order is created, spot status becomes open.
  • Periodically gets transactions, associated with orders for their status. Callbacks can be also used for this functionality. When transaction is reserved, client should revoke or confirm it. Only when transaction is confirmed, the order is fully paid, as the transaction can be changed between reserving it and getting this information for the merchant.
  • Closes spot after all transaction(s), that are associated with order(s) were paid, order(s) were paid in cash, etc. Spot status becomes closed and is ready to accept new clients.

Each spot has to have its own code. This code will be used for retrieving spot by client. The code is formed of prefix PAYSERA*, followed by location ID (location where this spot is located) and spot identifier, separated by colon. Spot identifier is recommended to contain only uppercase letters, space or digits for QR code to be smaller and more easily read by mobile applications. Though spot identifier can be chosen freely and is automatically registered in the system on the first request with such code. Example of code: PAYSERA*3:TABLE1.

Warning Auto-register of spots allows to easily add more tables etc., but merchant client should implement automatically closing the spots with non-existing identifiers as invalid QR code can be easily fabricated by any user.

Finding spots by status

Request

GET https://wallet.paysera.com/rest/v1/spots?status=:status&limit=:limit&offset=:offset

Parameters

status
Spot status

Response data structure

Parameter
Type
Remarks
Description
spots
array of objects
always
Each item in array is spot object
_metadata
object
always
Additional information about result

Metadata information structure

Parameter
Type
Remarks
Description
total
integer
always
Total count of results, ignoring limit parameter
offset
integer
always
Used offset parameter for filtering events
limit
integer
always
Used limit - maximum count of available results in single response

Example request

GET /rest/v1/spots?status=waiting&limit=3 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="Uawl/ym+bO801+pgQQlgSKXFyMulwcOUGqoWZAKKrhI="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "spots": [
        {
            "id": 15,
            "status": "waiting",
            "identifier": "table1",
            "place_info": {
                "title": "Cool caffe",
                "description": "Coffee and cakes for everyone, even you!",
                "address": "address"
            }
        }
    ],
    "_metadata": {
        "total": 1,
        "offset": 0,
        "limit": 3
    }
}

Closing spots

When closing spot, all pending orders in that spot are closed too.

Request

PUT https://wallet.paysera.com/rest/v1/spot/:id/close

Example request

PUT /rest/v1/spot/1/close HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="aiRHKuK/w48Xaxb9OiCcc1tQXK5zYIOk4L/mWwY0Wtc="

Response data structure

Spot data structure is returned.

Creating and editing orders

Created or edited order will be associated with transaction by using transaction key. So transaction must be provided when creating or editing order in one of ways:
  • Transaction can be created in advanced and then its key provided in the request.
  • Transaction object can be provided in the request.

Request

Create order: 
POST https://wallet.paysera.com/rest/v1/spot/:id/order
Edit order: 
PUT https://wallet.paysera.com/rest/v1/order/:id

Request body structure

When providing only transaction key:
Parameter
Type
Remarks
Description
transaction_key
string
required
Key of existing transaction
When providing transaction object:
Parameter
Type
Remarks
Description
transaction
transaction object
required
Transaction object
Info Please refer to documentation section about creating transactions for more information.

Example request

Create order: 
POST /rest/v1/spot/1/order 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="ohPt7bbwTxtqXDnXLtRC82iI1EkPEwoVI1Ya9xMmDhc=", ext="body_hash=CGmZSkySf2IjkLaY8h1isHhIfV0s4zB45DtYKGYG1Ds%3D"
{
    "transaction_key": "Pu5CPePCkm3TJPlkcbcshzkIlxeLU3WR"
}
Edit order: 
PUT /rest/v1/order/52 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="rR/gwtiNhTSonuIgKXqJlMLLSBZfgjAgaahZLN4G43s=", ext="body_hash=CGmZSkySf2IjkLaY8h1isHhIfV0s4zB45DtYKGYG1Ds%3D"
{
    "transaction_key": "Pu5CPePCkm3TJPlkcbcshzkIlxeLU3WR"
}

Response data structure

Order data structure is returned.

Removing orders

Request

Create order: 
DELETE https://wallet.paysera.com/rest/v1/order/:id

Example request

DELETE /rest/v1/order/52 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="hQUsJo76gvf1SBfxBdOqOj4SMReoME3z8x+lI8zERqA="

Response data structure

Order data structure is returned.