Tpay.com Centrum Wsparcia

Płatności mobilne BLIK są cieszącą się coraz większą popularniejszą metodą dokonywania zapłaty na rynku e-commerce.

Ten poradnik 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 - bez potrzeby przekierowania klienta do zewnętrznych stron.

Mechanizm płatności BLIK Level 0

To najprostsza metoda integracji, polegająca na udostępnieniu w swoim sklepie pola do wprowadzenia sześciocyfrowego kodu BLIK

04.developer/

W pierwszej kolejności należy dodać możliwość wyboru metody płatności BLIK swoim klientom, poprzez np. wyświetlenie dodatkowego przycisku "Szybka płatność BLIKIEM" lub dodanie tej metody pośród innych banków np.
Po wybraniu metody BLIK, należy wyświetlić klientowi pole, w które będzie mógł wprowadzić sześciocyfrowy kod, wygenerowany w jego mobilnej aplikacji bankowej oraz regulamin płatności Tpay.
Po zatwierdzeniu wprowadzonego kodu, akcję sprawdzenia można wykonać poprzez natychmiastowe przekazanie go w tle i wyświetlenie rezultatu lub kliknięcie przycisku "Składam zamówienie". Wybór rozwiązania zależy od możliwości technicznych sklepu, w którym wdrażane jest to rozwiązanie.
Na tym etapie zamówienia, nasz system zwróci informację o tym, czy wprowadzony został poprawny kod BLIK, a pytanie o potwierdzenie płatności zostało wyświetlone klientowi w jego aplikacji.
Jeżeli wszystko przebiegło poprawnie, należy wyświetlić podziękowanie i umożliwić ponowną płatność poprzez kliknięcie w link do transakcji, gdyż nie wiadomo jeszcze czy klient zatwierdził płatność w swoim urządzeniu.
Po udanym zatwierdzeniu transakcja zostanie sfinalizowana, środki przypisane do konta sprzedawcy, a powiadomienia o udanej płatności zostaną wysłane do klienta oraz sprzedawcy.

Techniczne wyjaśnienie płatności BLIK Level 0

W momencie złożenia zamówienia, serwis powinien dysponować już danymi zamawiającego, takimi jak adres email oraz imię i nazwisko, które będą wymagane do przygotowania transakcji.
Transakcja powinna zostać utworzona zgodnie z poradnikiem Tworzenie transakcji przez API.
Integracja metody BLIK na stronie sklepu polega na przesłaniu danych płatności BLIK przez API, zamiast wykonywania przekierowania do panelu transakcyjnego Tpay.
Dysponując identyfikatorem utworzonej transakcji należy przesłać kod BLIK wprowadzony przez klienta metodą POST /transactions/{transactionId}/pay
Zestaw parametrów (w formacie JSON), jakie powinny zostać wysłane w tym przypadku to:
```
{
  "groupId": 150,
  "blikPaymentData": {
    "blikToken": 123456
  }
}
```
Metoda ta zwróci rezultat pozytywny jeśli wprowadzony kod BLIK jest poprawny i udało się wyświetlić powiadomienie w aplikacji mobilnej klienta.
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 przy przekierowaniu klienta do panelu transakcyjnego. Przeczytaj Jak odebrać powiadomienie POST o płatności

Mechanizm płatności BLIK ONE CLICK

Metoda płatności one click jest rozszerzeniem płatności "level 0" o możliwość zapamiętania urządzenia, z którego najczęściej korzysta klient do finalizacji transakcji. Interfejs użytkownika zostaje rozszerzony o możliwość wyboru zapłaty nowym kodem BLIK (np. kiedy zmieniony zostanie bank lub urządzenie mobilne) lub zapamiętanym urządzeniem, dokładnie tak samo jak po zapamiętaniu karty płatniczej.

Przed rozpoczęciem integracji tego typu, należy wykonać kroki implementacji level 0, gdzie płatność odbywa się poprzez wprowadzenie sześciocyfrowego kodu BLIK na stronie sklepu.
W modelu one click, każdy zalogowany użytkownik powinien mieć automatycznie wygenerowany losowy ciąg znaków (liter oraz cyfr), który zostanie przypisany do jego konta w sklepie. Wspomniany ciąg znaków to tzw. alias, który będzie identyfikował go w kolejnych zakupach.
Nowy klient, który płaci blikiem po raz pierwszy, będzie musiał wprowadzić sześciocyfrowy kod BLIK, lecz z możliwością skojarzenia sklepu, ze swoją aplikacją bankową.
Po złożeniu zamówienia, tak jak w modelu "level 0", w aplikacji mobilnej banku klienta zostanie wyświetlony monit o zatwierdzenie transakcji, a następnie pytanie czy zapamiętać sklep, w którym dokonał właśnie płatności.
Jeżeli klient wyrazi zgodę, to za następne zakupy będzie mógł zapłacić bez wprowadzania kodu. Korzystając z wygenerowanego aliasu można skojarzyć więcej niż jedną aplikację bankową ze sklepem, dlatego zawsze należy wyświetlić wybór zapłaty nowym lub zapamiętanym urządzeniem.
W przypadku wyboru zapamiętanej aplikacji, nie ma potrzeby wprowadzania żadnych kodów, a monit o akceptację transakcji pojawia się natychmiast po kliknięciu "złóż zamówienie".
Każdy klient ma później możliwość usunięcia skojarzenia swojej aplikacji bankowej z danym sklepem, dlatego nasz system wysyła odpowiednie powiadomienia aby utrzymać listę aktualną.

Techniczne wyjaśnienie płatności BLIK ONE CLICK

W modelu One Click do podstawowej funkcjonalności (level 0), gdzie przesyłany jest identyfikator transakcji oraz kod wprowadzony przez klienta, dodana zostaje tablica danych, zawierająca informacje o aliasie. Alias to losowy ciąg znaków i cyfr, przypisany do konta użytkownika, który identyfikowany jest przy próbie wykonania płatności bez konieczności wprowadzenia kodu blik.
Alias powinien zostać wygenerowany i przypisany do klienta przez system sprzedawcy oraz być unikatowy.

Pierwsza płatność klienta metodą BLIK, musi odbyć się poprzez wprowadzenie sześciocyfrowego kodu BLIK - tak samo jak w modelu level 0, natomiast dodatkowo należy rozszerzyć zapytanie o zestaw parametrów:
```
{
  "groupId": 150,
  "blikPaymentData": {
    "blikToken": 123456,
    "aliases": {
      "value": "user_unique_alias_123",
      "type": "UID",
      "label": "Shop label"
    }
  }
}
```
W powyższym przykładzie przesłane są wartości odpowiadają kolejno:
- value - parametr, w którym przesyłamy wartość aliasu przypisaną do użytkownika w integrowanym sklepie,
- label - to nazwa, która zostanie zwrócona gdy użytkownik zapisze alias w więcej niż jednej aplikacji bankowej
- type - obecnie obsługiwanym jest wyłącznie "UID" - "user identificator".
Po zatwierdzeniu transakcji, klient otrzyma dodatkowy komunikat w aplikacji bankowej, pozwalający zapisać sklep. Jeśli wyrazi zgodę, nasz system wyśle asynchroniczne powiadomienie POST na adres wynikowy sklepu (adres musi być zdefiniowany w Panelu Odbiorcy Płatności), z informacją o zapamiętaniu aliasu, które należy zaktualizować w bazie danych.
Przykład powiadomienia o rejestracji aliasu jest następujący:
```
{
   "id": "1010",
   "event": "ALIAS_REGISTER",
   "msg_value": [ 
      {
          "value": "user_unique_alias_123",
          "type": "UID"
      }
   ],
   "md5sum": "d303c5af701cdfcaed02f66603239eef"
}
```
W przypadku gdy powracający klient posiada już zarejestrowaną aplikację bankową, wystarczy wysłać parametry bez kodu BLIK (nie ma potrzeby jego wprowadzania):
```
{
  "groupId": 150,
  "blikPaymentData": {
    "aliases": {
      "value": "user_unique_alias_123",
      "type": "UID",
      "label": "Shop label"
    }
  }
}
```
Jeżeli z jakiegoś powodu nie uda się wyświetlić monitu o płatność - np. urządzenie z zapamiętaną aplikacją nie będzie miało aktualnie dostępu do Internetu, to po zwróceniu błędu przez nasze API należy umożliwić ponowną próbę zapłaty ale tym razem kodem BLIK - tak jak w modelu level 0 lub wykonać przekierowanie do utworzonej transakcji.

Przykład wdrożenia BLIK level 0 w oparciu o bibliotekę PHP Tpay

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.
04.developer/
W folderze Examples\TransactionsApi znajduje się plik BlikPayment.php zawierający klasę BlikPayment.
Klasa posiada konstruktor, który sprawdza czy należy wyświetlić formularz BLIK, czy procesować płatność. Na potrzeby przykładu jest to jeden plik.
Jeśli nie zostanie przesłany kod BLIK, klasa wyświetli formularz płatności:

Gdy zostanie przesłany kod BLIK, konstruktor klasy spowoduje rozpoczęcie procesowania płatności.
Klasa posiada metodę zwracającą parametry transakcji (na potrzeby przykładu są to dane statyczne), które posłużą do wygenerowania transakcji:

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' => 150,
        ],
    ];
}

Klasa posiada również metodę, która tworzy transakcję i próbuje opłacić ją przesłanym kodem BLIK. Jeśli kod BLIK nie jest poprawny, wykonuje przekierowanie do panelu transakcyjnego umożliwiając kolejną próbę:

protected function processPayment($blikCode)
{
    $TpayApi = new TpayApi(static::MERCHANT_CLIENT_ID, static::MERCHANT_CLIENT_SECRET, true, 'read');
    $transaction = $TpayApi->Transactions->createTransaction($this->getRequestBody());
    if (isset($transaction['transactionId'])) {
        $blikPaymentFields = [
            'groupId' => 150,
            'method' => 'transfer',
            'blikPaymentData' => [
                'blikToken' => $blikCode,
                'type' => 0,
            ],
        ];
        $result = $TpayApi->Transactions
             ->createPaymentByTransactionId($blikPaymentFields, $transaction['transactionId']);
        if (isset($result['result']) && $result['result'] === 'success') {
            //The BLIK code was valid, now the customer needs to confirm payment on his mobile app
            //Redirect client to thank you page and wait for asynchronous POST payment notification
            //Do not mark your order as paid here!
            echo 'BLIK code is valid';
        } else {
            //The BLIK code was incorrect, redirect to transaction panel to try again
            header('Location: '.$transaction['transactionPaymentUrl']);
        }
    } else {
        //Code error handling @see POST /transactions HTTP 400 response details
        throw new TpayException('Unable to create transaction. Response: '.json_encode($transaction));
    }
}

Na końcu pliku następuje wywołanie klasy:
```
new BlikPayment;
```