POPULAR_QUESTIONS

Odbieranie powiadomienia o wpłacie

Ostatnia aktualizacja: 19.07.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 parametruOpis
idIdentyfikator liczbowy przypisany do konta sprzedawcy w systemie Tpay
tr_idTytuł transakcji nadany w momencie jej tworzenia
tr_dateData utworzenia transakcji w formacie 'Y-m-d H:i:s'
tr_crcParametr zawierający dane przesłane w parametrze hiddenDescription (jeśli został przesłany), służące do identyfikacji numeru zamówienia w sklepie
tr_amountKwota docelowa transakcji, podana przy jej utworzeniu
tr_paidKwota zapłacona przez klienta
tr_descOpis transakcji podany przy jej tworzeniu
tr_statusStatus 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_emailAdres email klienta
md5sumSuma 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.

walletParametr informujący o wybranym portfelu kartowym. Jest obecny w powiadomieniu tylko gdy metoda płatności to MasterPass.
card_tokenToken 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

  1. Pobierz biblioteki Tpay z serwisu Github.
  2. 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.

  3. 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);
    }
  4. 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();