Tpay.com Centrum Wsparcia

Wdrożenie wyboru banków w koszyku płatności to najlepsza metoda prezentacji funkcjonalności płatniczych sklepu.

Ten tutorial pozwoli zarówno zrozumieć mechanizm działania tego rodzaju płatności jak i pomoże w poprawnym wdrożeniu ich na własnej stronie.

Zalety integracji z wyborem banków po stronie Twojego sklepu

Klient składający zamówienie od razu rozpozna swój bank na liście, co jeszcze bardziej zachęci go do finalizacji zakupu.
Jeśli prowadzisz sprzedaż w kilku sklepach, możesz niezależnie zdecydować, które banki udostępnić swoim płatnikom, bez konieczności rezygnacji z jednego banku na poczet drugiej strony.
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ł, 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.
Jeśli pobierasz prowizję za płatność danym bankiem, masz pewność, że płatnik nie zmieni go w panelu transakcyjnym, gdyż zostanie od razu skierowany do wybranej przez siebie grupy bankowej.
Utworzenie transackji przez API zapewnia dane do wpłaty, które można wyświetlić płatnikowi na swojej stronie zamiast wykonywać przekierowanie - metoda zwraca również numer konta oraz tytuł wpłaty (w przypadku banków obsługujących e-przelew)

Techniczne wyjaśnienie zasady integracji

Wprowadzenie wyboru banku w formie kafelków jest prostą modyfikacją kodu źródłowego strony koszyka, wiążącą się z dodaniem jednego formularza html oraz java skryptu pobierającego listę dostępnych banków i podświetlającego wybrany bank. Informacje jak pobierać listę banków znajdują się w dokumentacji grup bankowych Tpay.
Gotowy formularz można łatwo wygenerować korzystająć z gotowych bibliotek PHP Tpay, dostępnych w serwisie github.com.
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 create.
W odpowiedzi zostanie zwrócony między innymi tytuł płatności oraz link, na który należy przekierować klienta w celu finalizacji płatności. Wygenerowany tytuł 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, a także można wykonać testowe wywołanie klikając "Try" w dokumentacji.
Minimalny zestaw parametrów, jakie należy wysłać w tej metodzie to:
```
{
  "id": 1010,
  "amount": 13.99,
  "description": "Payment for order X",
  "md5sum": "6d6807ef9edd112bf09c1a9d10292ff6",
  "group": 150,
  "email": "[email protected]",
  "name": "john doe",
  "accept_tos": 1,
  "api_password": "p@$$w0rd#@!"
}
```
Po udanym zatwierdzeniu płatności przez klienta, na adres wynikowy serwera zostanie wysłane asynchroniczne powiadomienie o wpłacie, dokładnie tak samo jak w przypadku transferów bankowych. Przeczytaj Jak odebrać powiadomienie POST o płatności

Przykład wdrożenia na podstawie bibliotek PHP Tpay

Klasa wyświetlająca formularz wyboru banku

Pobierz biblioteki Tpay z serwisu Github.com

Stwórz plik (np. w folderze examples) rozszerzający klasę PaymentBasicForms, w którego konstruktorze podaj swoje podstawowe dane dostępowe:

<?php
namespace tpayLibs\examples;

use tpayLibs\src\_class_tpay\PaymentForms\PaymentBasicForms;

include_once 'loader.php';

class BankSelectionAPIExample extends PaymentBasicForms
{
    public function __construct()
    {
        $this->merchantSecret = 'demo';
        $this->merchantId = 1010;
        parent::__construct();
    }
}

Następnie dodaj metodę wywołującą generowanie formularza:
```
public function getBankForm()
{
    $form = $this->getSimpleBankList(false, false);
    echo $form;
}
```
- Pierwszy argument funkcji określa, czy pokazane mają być wyłącznie metody płatności zapewniające bierzące księgowanie.
- Drugi argument decyduje czy do formularza ma zostać dodana informacja o regulaminie płatności Tpay.
Zmienna $form zawiera w tym momencie kod HTML oraz JS, który możesz wyświetlić w dowolnym miejscu na swojej stronie. Wszystko zależy od zasad panujących w programowanym środowisku, a na potrzeby przykładu posłużymy się najprostszą funkją "echo".

Na końcu klasy dodaj jej wywołanie:

(new BankSelectionAPIExample())->getBankForm();

Klasa odbierająca wybrany numer banku i tworząca transakcję

Stwórz plik (np. w folderze examples) rozszerzający klasę TransactionApi, w którego konstruktorze podaj swoje podstawowe dane dostępowe do API transakcji:

<?php

namespace tpayLibs\examples;

use tpayLibs\src\_class_tpay\Utilities\TException;
use tpayLibs\src\_class_tpay\TransactionApi;

include_once 'loader.php';

class TransactionApiExample extends TransactionApi
{
    public function __construct()
    {
        $this->merchantSecret = 'demo';
        $this->merchantId = 1010;
        $this->trApiKey = '75f86137a6635df826e3efe2e66f7c9a946fdde1';
        $this->trApiPass = 'p@$$w0rd#@!';
        parent::__construct();
    }
}

Następnie dodaj funkcję, która odbierze wybrany numer banku oraz wykona zapytanie do serwera Tpay:

public function createTransaction()
{
    if (!isset($_POST['group'])) {
        //if group parameter has not been set, redirect back to bank choice site
        header('Location: BankSelectionAPI.php');
    }
    $config = array(
        'amount' => 0.20,
        'description' => 'Transaction description',
        'crc' => '100020003000',
        'result_url' => 'https://example.pl/TransactionNotificationHandler.php',
        'result_email' => '[email protected]',
        'return_url' => 'http://example.pl/success',
        'email' => '[email protected]',
        'name' => 'John Doe',
        'group' => (int)$_POST['group'],
        'accept_tos' => 1,
    );
    try {
        $response = $this->create($config);
        echo '<a href="https://secure.tpay.com/?gtitle=' . $response['title'] . '">go to payment</a>';
    } catch (TException $e) {
        var_dump($e);
    }
}

Stworzona przez nas metoda sprawdzi czy został przesłany parametr grupy bankowej oraz spróbuje wykonać zapytanie API o utworzenie transakcji. Jeśli wszystko przebiegnie pomyślnie, zostanie zwrócony parametr 'title', zawierający tytuł transakcji, pod który należy wykonać przekierowanie.
Metoda create zwraca również inne parametry, na przykład numer rachunku do wpłaty (jeśli dany bank obsługuje e-przelew), co można wykorzystać do wyświetlania klientowi informacji o wpłacie na stronie sklepu, zamiast wykonywać przekierowanie. Wszystko zależy od aktualnych potrzeb.
Więcej informacji znajduje się w dokumentacji metody.

Na końcu klasy dodaj wywołanie:

(new TransactionApiExample())->createTransaction();