Tworzenie transakcji przez API

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

1. 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.
2. 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.
3. 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ę

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

3. 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'],
           ],
       ];
   }

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

5. Stworzenie transakcji nie musi skutkować przekierowaniem pod adres 'transactionPaymentUrl', jeśli na stronie udostępnimy formularz płatności BLIK lub kartą płatniczą.
6. Na końcu pliku następuje wywołanie klasy i metody:
   

   (new RedirectPayment)->processTransaction();