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

  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();

Chcesz o coś zapytać?

Odpowiemy na Twoje pytanie najszybciej jak to możliwe.