English

Push Notifications

This chapter describes methods to be used to get push notifications to the phone. Push notifications are available only for clients with type app_client, that is, applications in phones.

Following scheme is used to provide push notifications for the user:

  • Client subscribes to events, providing event names and filters.
  • Push notification is sent after each subscribed event with basic event information.
  • Client gets all pending events from API with full information.
  • Client unsubscribes from events to stop push notifications. Notifications also stops after access token is invalidated.

Events and their subscriptions are always bound to access token - if new access token is issued, client must re-subscribe to the events. All methods must be accessed with access token to work.

Subscribe to events

This method is used to subscribe to events and send push notifications for each of them.

Request

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

Request body structure

Parameter
Type
Remarks
Description
type
string
required
One of android, ios or windows, depending on push notification type
recipient
object
required
Structure depends on type parameter, see more information below
events
array of objects
required
Events to subscribe to, see more information below
locale
string
optional
Locale to use for messages in push notifications. Defaults to current user's locale
privacy_level
string
required
One of low or high, defaults to low. If low is provided, push notification messages can include private information about user (for example, statement details and amount). If high is provided, only basic information about an event is provided in the message.

Subscribing for Android operating system

To subscribe to push notifications on Android system, Google Cloud Messaging (GCM) is used.

android should be provided as type parameter to use GCM.

Recipient data structure for GCM notifications

Parameter
Type
Remarks
Description
identifier
string
required
Registration ID for the device

Subscribing for iOS operating system

To subscribe to push notifications on iOS system, Apple Push Notification Service (APNS) is used.

ios should be provided as type parameter to use APNS.

Recipient data structure for APNS notifications

Parameter
Type
Remarks
Description
identifier
string
required
APNS device token

Subscribing for Windows operating system

To subscribe to push notifications on Windows system, Microsoft Push Notification Service (MPNS) is used.

windows should be provided as type parameter to use WNS.

Recipient data structure for MPNS notifications

Parameter
Type
Remarks
Description
uri
string
required
Notification channel URI
notification_type
string
required
One of toast or tile
tile_id
string
optional, available only if notification_type is tile
ID of the tile to display notification in

Event types and parameters

events field consists of array of objects. Structure of each is detailed below.

Parameter
Type
Remarks
Description
event
string
required
Event identifier, comes together with object
object
string
required
Object type for which event occured, comes together with event
silent
boolean
optional
Whether this notification should be sent without push message. Defaults to false. Depending on server-side configuration, some events can be always silent
parameters
object
optional or required, depending on event and object
Structure depends on event and object, see more details below

Parameters structure is detailed for each event together with their data structure in the dedicated chapter below.

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of this subscriber
status
string
always
One of active or inactive
type
string
always
One of android, ios or windows
recipient
object
always
Recipient identification structure
events
array of objects
always
Subscribed events
locale
string
if provided
Locale to use for messages in push notifications. Defaults to current user's locale
privacy_level
string
always
One of low or high

Example request

POST /rest/v1/subscriber 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="psKZakOgkSh20x3+DKdigSQnFB68UMv05dn+8B2PJFA=", ext="body_hash=UDiXhPga4Ivy8kZC%2Bqcwn2wsRCJELyXdVmPSxvpLH9w%3D"
{
    "type": "android",
    "recipient": {
        "identifier": "456489411212335678498135493"
    },
    "events": [
        {
            "event": "created",
            "object": "statement",
            "parameters": {
                "wallet_id": 97784,
                "direction": "in"
            }
        }
    ],
    "locale": "en",
    "privacy_level": "high"
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 19785,
    "status": "active",
    "type": "android",
    "recipient": {
        "identifier": "456489411212335678498135493"
    },
    "events": [
        {
            "event": "created",
            "object": "statement",
            "parameters": {
                "wallet_id": 97784,
                "direction": "in"
            }
        }
    ],
    "locale": "en",
    "privacy_level": "high"
}

Unsubscribing from events

These requests allow to unsubscribe from events. This stops push notifications and disables returning events from API to these subscriptions.

Request to unsubscribe from specific events

DELETE https://wallet.paysera.com/rest/v1/subscriber/:subscriberId

Parameters

subscriberId - ID of the subscriber

Response data structure

Response is subscriber structure, which was disabled.

Request to unsubscribe from all events

DELETE https://wallet.paysera.com/rest/v1/subscribers

Response data structure

Response is array of subscribers structures, which were disabled.

Modifying subscribed events

This method allows to modify a subscriber. This is same as unsubscribing from events and subscribing again to some different ones or with different parameters.

Request

PUT https://wallet.paysera.com/rest/v1/subscriber/:subscriberId

Request body structure

Request structure is the same as when subscribing to events.

Response data structure

Response structure is the same as when subscribing to events.

Getting events from API

Get single event

This is used to get a single event by its id. Must be requested with access token that is associated with the event.

Request

GET https://wallet.paysera.com/rest/v1/event/:eventId

Parameters

eventId - ID of event

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of this event
object
string
always
Type of the object, related to this event
event
string
always
Event identifier
data
object
always
Structure of the object. Depends on object parameter
subscriber_id
integer
always
Event subscriber id

Example request

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

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 1,
    "object": "user",
    "event": "registered",
    "data": {
        "display_name": "John S.",
        "user_id": 4457,
        "wallet_id": 25487,
        "account_number": "EVP6310001000103"
    },
    "subscriber_id": 1
}

Get events by ID range

This method returns information about events to which current client with current access token has subscribed.

Request

GET https://wallet.paysera.com/rest/v1/events?from=:from&limit=:limit

Parameters

from - ID of last seen event

limit - optional; defaults to 20, maximum allowed is 200

When from parameter is passed, only events with ID larger than the passed one will be returned. Also all events with ID equal or lower to the given one will be marked as read and will not be returned again.

Warning For the first call to this method, from parameter can be missing. If it is not provided for every next call, the same events will be returned.

Response data structure

Parameter
Type
Remarks
Description
events
array of objects
always
Each item in array is event object, which is detalized bellow
_metadata
object
always
Additional information about result

Event data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of this event
object
string
always
Type of the object, related to this event
event
string
always
Event identifier
data
object
always
Structure of the object. Depends on object parameter
subscriber_id
integer
always
Event subscriber id

Metadata information structure

Parameter
Type
Remarks
Description
total
integer
always
Total count of results, ignoring limit parameter
from
integer
always
Used from parameter for filtering events
limit
integer
always
Used limit - maximum count of available results in single response
next_from
integer
always
Value to use for from parameter in the next call

Example request

GET /rest/v1/events?from=2212 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="d19yQJGsABeV5mQdx6JvKUyhq7b0gs2ly/AIZNHKUSA="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "events": [
        {
            "id": 2213,
            "object": "statement",
            "event": "created",
            "data": {
                "id": 59418,
                "amount": 100,
                "currency": "EUR",
                "amount_decimal": "1.00",
                "direction": "in",
                "date": 1363340355,
                "details": "Currency exchange 1.23 USD -> 1.00 EUR (Exchange rate 10 USD : 8.81142 EUR; 1.23 USD : 1 EUR)",
                "type": "currency",
                "transfer_id": 45375
            }
        },
        {
            "id": 2214,
            "object": "user",
            "event": "registered",
            "data": {
                "display_name": "John S.",
                "user_id": 4457,
                "wallet_id": 25487,
                "account_number": "EVP6310001000103"
            }
        }
    ],
    "_metadata": {
        "total": 2,
        "from": 2212,
        "limit": 20,
        "next_from": 2214
    }
}

Push notification payload structure

In the push notification, additional data in the payload is also provided with some basic information about event.

Additional payload parameters are detailed below.

Parameter
Type
Remarks
Description
id
integer
always
ID of this event. If last next_from is equal or biggen than this value, no event refresh is needed.
count
integer
Only for android type
Count of unread events. For iOS this value is used as aps.badge parameter

Available events and their data structures

New statement created

For this event object is statement and event is created.

Parameters data structure

Parameter
Type
Remarks
Description
wallet_id
integer
required
Wallet ID in which statements should be created for event to be fired. Use several events if several wallets are needed to be subscribed to
direction
string
optional
One of in or out. Filters statements by their direction. No value means events will be fired for both in and out directions

Response data structure

Statement data structure is used in the event response.

Balance has changed

For this event object is account_balance and event is changed. Currently this event will send anything to the user only for Windows Tile notifications.

Parameters data structure

Parameter
Type
Remarks
Description
wallet_id
integer
required
Wallet ID in which balance must be changed for event to be fired. Use several events if several wallets are needed to be subscribed to
convert_to
string
required
Currency to convert balance for each separate currency to. Works same as convert_to parameter when getting the account balance

Response data structure

Parameter
Type
Remarks
Description
account_number
string
always
Number of the account
balance
object
always
Balance structure as returned when getting account balance

New pending payment created

For this event object is pending_payment and event is created.

Parameters data structure

Structure for parameters is the same as when subscribing to statement created event.

Response data structure

Pending payment data structure is used in the event response.

New transaction request created

For this event object is transaction_request and event is created.

Parameters are unavailable for this event.

Response data structure

Transaction request data structure is used in the event response.

New user has registered in Paysera system

For this event object is user and event is registered.

Parameters data structure

Parameter
Type
Remarks
Description
emails
array of strings
optional
Array of emails for which new user's registration event should be fired
phones
array of strings
optional
Array of phone numbers for which new user's registration event should be fired; 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 for which new user's registration event should be fired; 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 for which new user's registration event should be fired; each phone must start with country code without 00 or + sign and contain only digits before hashing. SHA1 result must be in hex format
contact_book_id
integer
optional
ID of created user's contact book. If book is updated, notification will be fired for these new contacts, no need to re-subscribe to this event
Warning Atleast one parameter must be specified!

Response data structure

User info data structure is used in the event response.

Some user has appeared nearby

For this event object is user_position and event is appeared.

This event is fired when some user has provided position nearby given coordinates. No event is fired when position is deleted or when position has changed.

Parameters data structure

Parameter
Type
Remarks
Description
lat
float
required
Latitude coordinate of interested position
lng
float
required
Longitude coordinate of interested position
distance
integer
optional, defaults to 500
Distance in meters from given coordinates to give notifications for

Response data structure

Distance to user structure is used in the event response, the same as when getting user positions.

Custom event

For this event object is information and event is alert.

This event is used to provide important or possibly relevant information to the user without particular structure or object.

Parameters are unavailable for this event.

Response data structure

Parameter
Type
Remarks
Description
message
string
always
Message to display for the user