Odbieranie powiadomienia o wpłacie
Ostatnia aktualizacja: 15.12.2024
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();