Odbieranie powiadomienia o wpłacie
Ostatnia aktualizacja: 15.01.2025
Poprawne odebranie powiadomienia o wpłacie z systemu Tpay jest gwarancją bezpieczeństwa i niezawodności komunikacji
Ten poradnik pozwoli zarówno zrozumieć mechanizm wysyłania powiadomień o wpłatach jak i pomoże w poprawnym wdrożeniu ich odbierania we własnym sklepie.
Zasady wysyłania powiadomień
- Wszystkie powiadomienia o wpłatach są wysyłane w sposób asynchroniczny, co oznacza, że nie bierze w nich udziału klient - osoba obsługująca przeglądarkę internetową. Komunikacja odbywa się na linii serwera sprzedawcy i serwera Tpay.
- System Tpay wysyłając powiadomienie oczekuje udzielenia poprawnej odpowiedzi, czyli wyświetlenie słowa TRUE na pustej stronie. Jeśli taka informacja nie zostanie wyświetlona, system ponowi wysyłkę do 37 razy.
- Odpowiedź FALSE jest uznawana za poprawną, tylko i wyłącznie gdy konto sprzedawcy jest w trybie dwuetapowego przyjmowania płatności.
- Do poprawnego odebrania powiadomienia wymagany jest kod bezpieczeństwa, dostępny w panelu odbiorcy płatności, w zakładce Ustawienia->Powiadomienia->Bezpieczeństwo.
Zasady bezpieczeństwa
Każde odebrane żądanie powinno zostać zweryfikowane na kilku płaszczyznach:
- walidacja adresu IP serwera z którego wysłano powiadomienie,
- walidacja czy przesłane parametry są zgodne z danymi, jakie zostały wysłane do serwisu płatności (kwota, id zamówienia),
- walidacja czy suma kontrolna przesłana pod kluczem md5sum jest prawidłowa,
- walidacja czy taka transakcja już nie została potwierdzona wcześniej.
Dane zwracane w powiadomieniu o wpłacie
| Nazwa parametru | Opis |
| id | Identyfikator liczbowy przypisany do konta sprzedawcy w systemie Tpay |
| tr_id | Tytuł transakcji nadany w momencie jej tworzenia |
| tr_date | Data utworzenia transakcji w formacie 'Y-m-d H:i:s' |
| tr_crc | Parametr zawierający dane przesłane w parametrze hiddenDescription (jeśli został przesłany), służące do identyfikacji numeru zamówienia w sklepie |
| tr_amount | Kwota docelowa transakcji, podana przy jej utworzeniu |
| tr_paid | Kwota zapłacona przez klienta |
| tr_desc | Opis transakcji podany przy jej tworzeniu |
| tr_status | Status transakcji:
'TRUE' dla transakcji poprawnej
'CHARGEBACK' dla transakcji zwróconej ręcznie w Panelu Odbiorcy Płatności
'PAID' dla transakcji opłaconej - tylko gdy konto sprzedawcy jest w trybie dwuetapowego przyjmowania płatności |
| tr_error | 'none' - brak błędów.
'overpay' - klient dokonał nadpłaty - może wystąpić tylko gdy w ustawieniach konta jest włączone przyjmowanie nadpłat.
'surcharge' - klient zapłacił za mało - może wystąpić tylko gdy w ustawieniach konta jest włączone przyjmowanie niedopłat i kwota zapłacona mieści się w progu przyjmowanych niedopłat. |
| tr_email | Adres email klienta |
| md5sum | Suma kontrolna md5 liczona z parametrów id+tr_id+tr_amount+tr_crc+merchant_confirmation_code |
| test_mode | Parametr informujący czy transakcja została wykonana w trybie testowym czy produkcyjnym:
'1' - tryb testowy.
'0' - tryb produkcyjny. |
| wallet | Parametr informujący o wybranym portfelu kartowym. Jest obecny w powiadomieniu tylko gdy metoda płatności to MasterPass. |
| card_token | Token zapisanej karty klienta, służący do kolejnych obciążeń jego karty. Parametr jest obecny w powiadomieniu tylko jeśli dokonano płatności kartą z opcją jej zapisania. |
Przykład odebrania powiadomienia na podstawie biblioteki PHP Tpay
- Pobierz biblioteki Tpay z serwisu Github.
- W folderze Examples znajduje się plik ExamplesConfig.php, w którym podaj swój kod bezpieczeństwa w stałej:
const MERCHANT_CONFIRMATION_CODE = 'demo';
Dane dostępowe nie muszą być podane w pliku ExamplesConfig, można wykorzystać własne źródło danych. Plik ten jest wykorzystywany tylko na potrzeby przykładu.
- W folderze Examples\Notifications znajduje się plik PaymentNotificationExample.php zawierający klasę PaymentNotificationExample
Klasa posiada metodę weryfikującą powiadomienie pod kątem poprawności adresu IP serwera, kompletności powiadomienia, zgodności sumy kontrolnej oraz wykonującą rzutowanie parametrów:
public function checkPayment()
{
$NotificationWebhook = new PaymentNotification;
return $NotificationWebhook->getNotification('TRUE', static::MERCHANT_CONFIRMATION_CODE);
}
- Tak zweryfikowane powiadomienie zwróci obiekt BasicPayment zawierający zweryfikowane obiekty w zmiennych publicznych odpowiadające nazwami parametrom powiadomienia.
Przykładowo aby odebrać powiadomienie i pobrać wartość parametru 'tr_id' należy wykonać:
$notification = (new PaymentNotificationExample)->checkPayment();
$transactionTitle = $notification->tr_id->getValue();
