Tworzenie transakcji przez API to najlepszy sposób komunikacji z systemem Tpay
Ten tutorial pozwoli zarówno zrozumieć mechanizm działania tworzenia transakcji jak i pomoże w poprawnym wdrożeniu go we własnym sklepie.
Zalety tworzenia transakcji przez API
- Proces tworzenia transakcji odbywa się w tle, dzięki czemu jest cały czas pod kontrolą programisty. Dane nie są przesyłane w formie jawnej, dlatego nie mogą być modyfikowane przez kupujących w przeglądarce.
- Od momentu utworzenia transakcji znany jest jej tytuł oraz link, dzięki czemu możliwe jest wysyłanie przypomnień o transakcji do płatników własnym mailingiem oraz umożliwianie ponownych prób płatności.
Techniczne wyjaśnienie zasady integracji
- Stworzenie transakcji w przez API wymaga podania identyfikatora metody płatności, który można pozyskać przez wdrożenie wyboru banków w koszyku płatności lub zapisanie go w przypadku znanych metod płatności jak karta płatnicza czy BLIK.
- Każda transakcja stworzona przez API zapewnia link prowadzący do panelu transakcyjnego, pod który można przekierować klienta, w celu finalizacji transakcji.
W przypadku niektórych metod płatności jak karta lub BLIK integrację można rozszerzyć o formularz podania szczegółów samej płatności jeszcze na stronie sklepu i zlikwidować potrzebę przekierowania. Nie jest to jednak konieczne. - Po odebraniu informacji o numerze banku wybranego przez klienta, należy wykonać zapytanie API, w którym zostaną przekazane podstawowe parametry transakcji takie jak kwota, numer zamówienia czy adres email płatnika, zgodnie z dokumentacją metody POST /transactions.
W odpowiedzi zostanie zwrócony między innymi identyfikator płatności oraz link, na który należy przekierować klienta w celu finalizacji płatności. Wygenerowany tytuł i identyfikator warto zapisać w bazie danych do późniejszego użytku.
Przykład wykonania tej metody znajduje się w serwisie Github w bibliotece PHP tpay-com.
Minimalny zestaw parametrów, jakie należy wysłać w tej metodzie to:{ "amount": 200.15, "description": "Transakcja testowa", "payer": { "email": "[email protected]", "name": "Jan Kowalski" }, "pay": { "groupId": 150 } }
Po udanym zatwierdzeniu płatności przez klienta, na adres wynikowy serwera zostanie wysłane asynchroniczne powiadomienie o wpłacie.
Adres wynikowy można zdefiniować statycznie w ustawieniach konta sprzedawcy lub przesyłać w metodzie POST /transactions dodając parametry:
"callbacks": {
"notification": {
"url": "https://my-website.com/notificationController.php"
}
}
Przeczytaj jak odebrać powiadomienie POST o płatności
Przykład wdrożenia na podstawie bibliotek PHP Tpay
Klasa odbierająca wybrany numer banku i tworząca transakcję
- Pobierz biblioteki Tpay z serwisu Github.
- W folderze Examples znajduje się plik ExamplesConfig.php, w którym podaj swoje dane dostępowe jako wartości stałych:
const MERCHANT_CLIENT_ID = '1010-e5736adfd4bc5d8c'; const MERCHANT_CLIENT_SECRET = '493e01af815383a687b747675010f65d1eefaeb42f63cfe197e7b30f14a556b7';
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\TransactionsApi znajduje się plik RedirectPayment.php zawierający klasę RedirectPayment
Klasa posiada metodę zwracającą parametry transakcji (na potrzeby przykładu są to dane statyczne):protected function getRequestBody() { return [ 'amount' => 0.10, 'description' => 'test transaction', 'hiddenDescription' => 'order_213', 'payer' => [ 'email' => '[email protected]', 'name' => 'John Doe', ], 'callbacks' => [ 'notification' => [ 'url' => 'https://example.com/notification', ], 'payerUrls' => [ 'success' => 'https://example.com/success', 'error' => 'https://example.com/error', ], ], 'pay' => [ 'groupId' => (int)$_POST['groupId'], ], ]; }
- Klasa posiada również publiczną metodę, która sprawdza, czy został przesłany identyfikator metody płatności, a następnie tworzy transakcję przez API i wykonuje przekierowanie do panelu transakcyjnego:
public function processTransaction() { if (!isset($_POST['groupId'])) { throw new TpayException('No payment group Id, unable to create transaction'); } $TpayApi = new TpayApi(static::MERCHANT_CLIENT_ID, static::MERCHANT_CLIENT_SECRET, true, 'read'); $result = $TpayApi->Transactions->createTransaction($this->getRequestBody()); if (isset($result['transactionPaymentUrl'])) { header('Location: '.$result['transactionPaymentUrl']); } else { //Code error handling @see POST /transactions HTTP 400 response details throw new TpayException('Unable to create transaction. Response: '.json_encode($result)); } }
- Stworzenie transakcji nie musi skutkować przekierowaniem pod adres 'transactionPaymentUrl', jeśli na stronie udostępnimy formularz płatności BLIK lub kartą płatniczą.
- Na końcu pliku następuje wywołanie klasy i metody:
(new RedirectPayment)->processTransaction();