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

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="Hqh+dFOt3dgtWyFSeC75Kwr7HF7nEGWaTEed3BWlARI=", 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="zz0+aQPjkNUZc8lSyjhIuCIfM03HYX1SY1WwoJ3742s="

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="rTKRLDOm8S/q7UCoJ6G1k8qHhaV9N39ZIfWhAHdr/Mo="

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