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 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 - 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

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

Wykonanie transakcji BLIK odbywa się poprzez wysłanie odpowiednich zapytań przez API. Do rozpoczęcia integracji będą potrzebne klucz i hasło API, które należy wygenerować zgodnie z instrukcją.
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.
Pierwszy krok to wywołanie metody create, służącej do wygenerowania nieopłaconej transakcji z kanałem BLIK (parametr grupa z wartością 150). Metoda ta generuje i zwraca tytuł transakcji w formacie TR-XXX-XXXXXX na podstawie podstawowych danych takich jak kwota, opis transakcji, email klienta i wskazana grupa płatności - w tym wypadku BLIK. Przykład wykonania tej metody znajduje się w serwisie github w bibliotece PHP tpay, 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#@!"
}
```
Drugi krok, to wykonanie metody blik, w której przesłany zostanie tytuł transakcji wygenerowany w kroku pierwszym oraz kod BLIK wprowadzony przez klienta. Przykład wykonania tej metody w języku PHP znajduje się w bibliotece PHP, w serwisie github. 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.
Kod, którym w trybie testowym można przetestować płatność blikiem to 123456.
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.

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ć wybierając z listy swój zapamiętany bank. 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 one click do podstawowej funkcjonalności (level 0), gdzie przesyłany jest tytuł 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.

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 udostępnić checkbox pozwalający podjąć decyzję, czy jego aplikacja ma zostać zapamiętana. Jeżeli klient wyrazi zgodę, to wykonanie metody API Blik, zostanie rozszerzone o zestaw dodatkowych parametrów:
```
{
  "groupId": 150,
  "blikPaymentData": {
    "blikToken": "123456",
    "aliases": {
        "value": "TPAY_ALIAS",
        "type": "UID",
        "label": "My qwerty bank"
    }
  }
}
```
W powyższym przykładzie przesłane są wartości testowe ale w trybie produkcyjnym powinny zostać zastąpione:
- value - parametr, w którym przesyłamy wartość aliasu przypisaną do użytkownika w integrowanym sklepie,
- label - to nazwa, pod jaką zostanie zapamiętany sklep, w aplikacji mobilnej klienta,
- 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 (zdefiniowany w panelu odbiorcy płatności), z informacją o zapamiętaniu aliasu, które należy zaktualizować w bazie danych.
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"
    }
  }
}
```
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.

W przypadku, gdy dany alias został zarejestrowany w więcej niż jednej aplikacji bankowej, nasz system zwróci informacje z błędem.

Dane zwrócone przez nasze API będą miały następujący format:

"payments": {
    "status": "pending",
    "method": "pay_by_link",
    "amountPaid": 0,
    "date": {
      "realization": null
    },
    "errors": [
      {
        "errorCode": "payment_failed",
        "errorMessage": "aliases: Too many aliases found for aliasValue: user_unique_alias_123"
      }
    ],
    "alternatives": [
      {
        "applicationName": "My qwerty bank",
        "applicationCode": "1ec8f352-463c-6334-be44-9fede70e64b8"
      },
      {
        "applicationName": "My azerty bank",
        "applicationCode": "1ec8fe63-ea6e-6b48-ac6f-f7f170888d37"
      }
    ]
}

W tej sytuacji należy wyświetlić klientowi dodatkowy wybór (np. listę rozwijaną), gdzie będzie mógł doprecyzować z jakiego banku chce dokonać płatności.
Następnie przesyłany zostać powinien ten sam alias, rozszerzony w wskazany przez użytkownika klucz:

{
  "groupId": 150,
  "blikPaymentData": {
    "aliases": {
        "value": "user_unique_alias_123",
        "type": "UID",
        "key": "1ec8f352-463c-6334-be44-9fede70e64b8"
    }
  }
}

Wdrożenie metody BLIK na stronie sklepu