Tworzenie transakcji przez API
Ostatnia aktualizacja: 08.12.2024
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();