API wiadomości

API wiadomości pozwala na otrzymywanie wiadomości o wydarzeniach na kontach i informacji o nich. Zamówić wiadomości konta na określony adres URL można na stronie ustawień konta Paysera. Na stronie ustawień konta Paysera można wpisać jeden lub więcej adresów i warunków, które muszą być spełnione przed powiadamianiem systemu.

Jeżeli używasz języka programowania PHP, możesz korzystać z biblioteki NotificationPhpClient.

Struktura wiadomości powiadamiającej

Zapytanie POST jest wykonywane dla każdego wydarzenia na podane przez Ciebie adresy. Przekazywane są 2 parametry:

  • data - zaszyfrowane dane o wydarzeniu;
  • sign - zaszyfrowany podpis parametru data.

Aby przetworzyć otrzymaną wiadomość należy sprawdzić czy parametr sign jest ważny i tylko wówczas odszyfrować parametr data.

Oba parametry są zaszyfrowane za pomocą systemu kodowania base64. Po zaszyfrowaniu, symbole + są zamieniane na -, / są zamieniane na _. Zaszyfrowany wierz odszyfrowuje się za pomocą algorytmu odwrotnego:

  1. Symbol - jest zamieniany na +, symbol _ jest zamieniany na /
  2. Rozszyfrowanie jest wykonywane za pomocą systemu kodowania base64.

Podpis parametru data stawia się korzystając z klucza RSA, za pomocą funkcji skrótu SHA1. Certyfikat, zgodny z kluczem, wykorzystanym do podpisu, można pobrać pod następującym adresem:

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

Dane o wydarzeniu są szyfrowane w formacie "application/x-www-form-urlencoded" przed szyfrowaniem w formacie base64 i zmianą spec. symboli. Aby otrzymać macierz danych, korzystaj z dekodowania formatu "application/x-www-form-urlencoded".

Przykład w języku PHP, pokazujący jak przetworzyć wiadomość powiadamiającą:

<?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 Jeżeli używasz języka PHP, polecamy korzystać z podanej biblioteki, która wykonuje rozszyfrowanie automatycznie.
Info Jeżeli wszystko jest pomyślnie wykonane, skrypt Callback powinien wrócić odpowiedź, rozpoczynającą się od lub zawierającą tylko "OK".

Przykładowe znaczenia, wykorzystane w przykładzie

$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
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"
}
            

Parametry wydarzeń

Po sprawdzeniu podpisu i rozszyfrowaniu parametru data, otrzymujesz informację o wydarzeniu. Jeżeli chociaż by jeden z parametrów jest pusty, on nie będzie zawarty w wierszu symboli, zakodowanych w formacie "application/x-www-form-urlencoded".

Nazwa parametru Znaczenie Przykład
type Zawsze podawany. Jeden z identyfikatorów rodzaju danego wydarzenia MK
credit 1 jeżeli to środki wchodzące, 0 jeżeli to środki wychodzące, niepodawany jeżeli to operacja wymiany waluty 1
account Numer konta. To przedmiot wydarzenia EVP0000000000001
amount Ilość wchodzących/wychodzących środków. Zawsze dodatni. Część dziesiętna jest oddzielana kropką ("."). Nie podawany w przypadku operacji wymiany waluty 29.99
currency Waluta podawanej kwoty. Zawsze podawana razem z parametrem amount EUR
from_amount Podawany tylko w przypadku operacji wymiany waluty. Ilość środków wychodzących 10.00
from_currency Zawsze podawany z parametrem from_amount EUR
to_amount Podawany tylko w przypadku operacji wymiany waluty. Ilość środków wchodzących 34.54
to_currency Zawsze podawany z parametrem to_amount EUR
beneficiary_name Tylko dla przelewów wychodzących. Imię odbiorcy środków. Nie podawany, jeżeli nie jest wiadomy John Smith
beneficiary_code Tylko dla przelewów wychodzących. Kod odbiorcy środków (PESEL lub NIP). Nie podawany, jeżeli nie jest wiadomy 38001010000
beneficiary_account Tylko dla przelewów wychodzących. Numer konta odbiorcy środków LT001100000111100000
payer_name Tylko dla przelewów wchodzących. Imię płatnika. Nie podawany, jeżeli nie jest wiadomy John Smith
payer_code Tylko dla przelewów wchodzących. Kod płatnika (PESEL lub NIP). Nie podawany, jeżeli nie jest wiadomy 38001010000
payer_account Tylko dla przelewów wchodzących. Numer konta płatnika. Nie podawany, jeżeli nie jest wiadomy LT001100000111100000
details Szczegóły przelewu Payment for request no. 123456
transfer_id Unikalny identyfikator przelewu w naszym systemie 123456
reference_number Kod płatności. Nie podawany, jeżeli nie jest wiadomy AB12345
reference_to_beneficiary Kod klienta w systemie informacyjnym odbiorcy. Nie podawany, jeżeli nie jest wiadomy AB12345
reference_to_payer Kod klienta w systemie informacyjnym płatnika. Nie podawany, jeżeli nie jest wiadomy AB12345
statement_id Unikalny numer potwierdzenia przelewu
Ważne. Prosimy sprawdzić, czy wcześniej nie była otrzymana wiadomość z takim numerem. Prosimy go zachować
123456789
created_at Data utworzenia przelewu 1448615390

Identyfikatory rodzaju

MK Płatność
HO Zasilenie konta. Podawany tylko w poszczególnych wypadkach zasilenia konta - gdy system na pewno wie, że konto zostało zasilone przez osobę uprawnioną
FX Wymiana waluty
MM Inna transakcja