Notification API

Notification API allows you to subscribe to events on your account and get a callback for each of them. To subscribe to account events, use the account settings page. You can specify one or more callback addresses and also conditions to be met before notifying.

If you use PHP, you can use NotificationPhpClient library.

Structure of the callback request

POST request is made for each event to your given address(-es). 2 parameters are passed:

  • data - encoded data about the event that occurred;
  • sign - encoded signature of data parameter.

To process the callback, you must check if the sign passes the verification and, if it does, decode the data parameter.

Both parameters are encoded using the base64 encoding scheme. Afterwards, symbol + is replaced with -, and / with _. You have to decode the parameters applying the reverse actions:

  1. Replace the symbols in the text: - to +, _ to /;
  2. Decode the result using base64 encoding scheme.

Signature of data parameter is signed with RSA key, using SHA1 hash function. Certificate, related to the key of the signature, is available via the address:

https://www.paysera.com/download/public.key

Data about the event is URL-encoded before encoding with base64 and replacing special symbols. To get an array of data, use URL decoding.

Example code in PHP, how to handle the callback:

<?php

$publicKey = loadFromWeb();
$sign = $_POST['sign'];
$data = $_POST['data'];

$signReplaced = strtr($sign, array('-' => '+', '_' => '/'));
$signDecoded = base64_decode($signReplaced);
if (openssl_verify($data, $signDecoded, $publicKey, OPENSSL_ALGO_SHA1) === 1) {
    $dataReplaced = strtr($data, array('-' => '+', '_' => '/'));
    $dataDecoded = base64_decode($dataReplaced);
    parse_str($dataDecoded, $params);

    // use $params

    echo 'OK';
}

				
Info If PHP is your choice of language, we recommend using the provided library.
Info In case of success, callback script must return the response beginning with or equal to “OK”.

Example values from the given example

$sign
QRRnBKqW5agE8_xYxG-E-72lDj0q8M16Tcof-1LvzXCl_vY_rkCBkevy5y4V4UlwyC3vYwuPAVqZDzQtxvl6svlLpG7Lhl55MzOPNajOokzNza5LTiMLX77XuRyVd1JWxqIoWi9NmXrvJizoQwFJXSqDai7cULX0LSEHL5dSQIsZST27jBFVrRUbuGQO1d67eRuSh_s6ybqnbGH--Ti_xdhkhZNOVn2pHFvhNtSNp0iFdcHMEELIMpkCe-07ouO9cvGGmXUXSiMlLyrfJZ-kpaAvTC_GDzq5crE0hXFp-OkkAinAWun0-LmZOEZsYFUbBv8xQ8YuNI5-11wwS2W33g==
$signReplaced
QRRnBKqW5agE8/xYxG+E+72lDj0q8M16Tcof+1LvzXCl/vY/rkCBkevy5y4V4UlwyC3vYwuPAVqZDzQtxvl6svlLpG7Lhl55MzOPNajOokzNza5LTiMLX77XuRyVd1JWxqIoWi9NmXrvJizoQwFJXSqDai7cULX0LSEHL5dSQIsZST27jBFVrRUbuGQO1d67eRuSh/s6ybqnbGH++Ti/xdhkhZNOVn2pHFvhNtSNp0iFdcHMEELIMpkCe+07ouO9cvGGmXUXSiMlLyrfJZ+kpaAvTC/GDzq5crE0hXFp+OkkAinAWun0+LmZOEZsYFUbBv8xQ8YuNI5+11wwS2W33g==
$signDecoded
Agªâ€“å¨óüXÄo„û½¥=*ðÍzMÊûRïÍp¥þö?®@‘ëòç.áIpÈ-ïcZâ„¢4-Æùz²ùK¤nˆ^y335¨Î¢LÍÍ®KN#_¾×¹•wRVÆ¢(Z/Mâ„¢zï&,èCI]*Æ’j.ÜPµô-!/—R@‹I=»Å’U­¸dÕÞ»y’‡û:ɺ§laþù8¿ÅØd…“NV}©[á6ԍ§H…uÁÌBÈ2â„¢{í;¢ã½rñ†™uJ#%/*ß%Ÿ¤¥ /L/Æ:¹r±4…qiøé$)ÀZéôø¹â„¢8Fl`Uÿ1CÆ.4Ž~×\0Ke·Þ
$data
dHlwZT1NSyZjcmVkaXQ9MSZhY2NvdW50PUVWUDAwMDAwMDAwMDAwMDEmYW1vdW50PTIzLjA5JmN1cnJlbmN5PUxUTCZwYXllcl9hY2NvdW50PUVWUDAwMDAwMDAwMDAwMDImZGV0YWlscz1EZXRhaWxzJnRyYW5zZmVyX2lkPTk5OTk5OTk5
$dataReplaced
dHlwZT1NSyZjcmVkaXQ9MSZhY2NvdW50PUVWUDAwMDAwMDAwMDAwMDEmYW1vdW50PTIzLjA5JmN1cnJlbmN5PUxUTCZwYXllcl9hY2NvdW50PUVWUDAwMDAwMDAwMDAwMDImZGV0YWlscz1EZXRhaWxzJnRyYW5zZmVyX2lkPTk5OTk5OTk5
$dataDecoded
type=MK&credit=1&account=EVP0000000000001&amount=23.09&currency=EUR&payer_account=EVP0000000000002&details=Details&transfer_id=99999999
$params
array(8) {
    ["type"]=>
    string(2) "MK"
    ["credit"]=>
    string(1) "1"
    ["account"]=>
    string(16) "EVP0000000000001"
    ["amount"]=>
    string(5) "23.09"
    ["currency"]=>
    string(3) "EUR"
    ["payer_account"]=>
    string(16) "EVP0000000000002"
    ["details"]=>
    string(7) "Details"
    ["transfer_id"]=>
    string(8) "99999999"
}
            

Event parameters

After checking the signature and decoding the data, you get the actual parameters about the event. If any of the parameters is empty, it will not be included in the URL-encoded string.

Parameter name Details Example
type Always provided. One of type identifiers MK
credit 1 if it is incoming funds, 0 if it is outgoing funds, not provided if it is currency exchange 1
account Account number. It is the subject of the event EVP0000000000001
amount Amount of incoming/outgoing funds. Always positive. Decimal part is separated with dot ("."). Not provided if it is currency exchange 29.99
currency Currency of the amount provided. Always comes with amount EUR
from_amount Provided only in currency exchange. Amount of outgoing funds 10.00
from_currency Always comes with from_amount EUR
to_amount Provided only in currency exchange. Amount of incoming funds 34.54
to_currency Always comes with to_amount EUR
beneficiary_name Only for outgoing transfers. Name of the beneficiary. Not provided if unavailable John Smith
beneficiary_code Only for outgoing transfers. Code (personal or company) of the beneficiary. Not provided if unavailable 38001010000
beneficiary_account Only for outgoing transfers. Account number of the beneficiary LT001100000111100000
payer_name Only for incoming transfers. Name of the payer. Not provided if unavailable John Smith
payer_code Only for incoming transfers. Code (personal or company) of the payer. Not provided if unavailable 38001010000
payer_account Only for incoming transfers. Account number of the payer. Not provided if unavailable LT001100000111100000
details Details text of the transfer Payment for request no. 123456
transfer_id Identificator of the transfer in our system 123456
reference_number Reference number provided in the transfer. Not provided if unavailable AB12345
reference_to_beneficiary Reference to the beneficiary provided in the transfer. Not provided if unavailable AB12345
reference_to_payer Reference to the payer provided in the transfer. Not provided if unavailable AB12345
created_at Transfer creation date 1448615390

Type identifiers

MK Payment
HO Deposits
FX Currency exchange
MM Other transaction