English

Specifications

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 programming language, we recommend using the provided library.
Info In case of success, callback script must return a response beginning with or equal to 'OK'.

Values from the given example

Parameter
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Ž~×Ke·Þ
$data 
dHlwZT1NSyZjcmVkaXQ9MSZhY2NvdW50PUVWUDAwMDAwMDAwMDAwMDEmYW1vdW50PTIzLjA5JmN1cnJlbmN5PUVVUiZwYXllcl9hY2NvdW50PUVWUDAwMDAwMDAwMDAwMDImZGV0YWlscz1EZXRhaWxzJnRyYW5zZmVyX2lkPTk5OTk5OTk5JnN0YXRlbWVudF9pZD0xMjM0NTY3ODk=
$dataReplaced 
dHlwZT1NSyZjcmVkaXQ9MSZhY2NvdW50PUVWUDAwMDAwMDAwMDAwMDEmYW1vdW50PTIzLjA5JmN1cnJlbmN5PUVVUiZwYXllcl9hY2NvdW50PUVWUDAwMDAwMDAwMDAwMDImZGV0YWlscz1EZXRhaWxzJnRyYW5zZmVyX2lkPTk5OTk5OTk5JnN0YXRlbWVudF9pZD0xMjM0NTY3ODk=
$dataDecoded 
type=MK&credit=1&account=EVP0000000000001&amount=23.09&currency=EUR&payer_account=EVP0000000000002&details=Details&transfer_id=99999999&statement_id=123456789
$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"
    ["statement_id"]=>
    string(9) "123456789"
}

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
Type identifiers:
MK - Payment
HO - Deposits
FX - Currency exchange
MM - Other transaction
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
Identifier 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
statement_id
Unique statement id in our system.
Important. Check statement id. If the message was not received before, save this number
123456789
created_at
Transfer creation date
1448615390