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

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

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

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

Event types and parameters

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

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

Response data structure

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

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.

Response data structure

Event data structure

Metadata information structure

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.

Available events and their data structures

New statement created

For this event object is statement and event is created.

Parameters data structure

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

Response data structure

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

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

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