BLIK One Click

BLIK One Click (alias BLIK) pozwala klientowi zapłacić w sklepie bez wpisywania kodu BLIK — wystarczy jedno kliknięcie "Zapłać", a potwierdzenie pojawia się od razu w aplikacji bankowej klienta. Pod spodem zamiast kodu używamy aliasu — identyfikatora powiązanego na stałe z kontem klienta w konkretnym banku.

Uruchomienie One Click

One Click wymaga aktywacji po stronie Paymentic. Żeby włączyć go dla swojego punktu płatności, napisz na [email protected].

Certyfikacja BLIK One Click

Zanim BLIK pozwoli Ci produkcyjnie używać One Click, musisz przejść certyfikację BLIK-a — Polski Standard Płatności wymaga, żeby każdy sklep spełnił zestaw wymagań dotyczących UX, wyglądu przycisku płatności, komunikatów dla klienta i obsługi ekranu zgody na zapamiętanie aliasu. Pełną, aktualną checklistę (tzw. Level 0 / One Click Checklist) znajdziesz na stronie blik.com → Level 0 / One Click Checklist.

Po stronie Paymentic pomagamy w tym procesie — przygotuj screeny swojego checkoutu (ekran wyboru metody, ekran rejestracji aliasu, ekran płatności aliasem) i wyślij razem z wnioskiem o aktywację na [email protected]. Bez pozytywnej weryfikacji BLIK-a nie włączymy One Click na środowisku produkcyjnym.

Jak to działa w skrócie

Cykl życia One Click składa się z dwóch etapów:

1. Rejestracja aliasu — przy pierwszej płatności klient obok kodu BLIK wyraża zgodę na zapamiętanie płatności. Alias trafia do bazy i jest wiązany z Twoim identyfikatorem klienta.
2. Płatność aliasem — przy kolejnych zakupach klient klika "Zapłać One Click", a Paymentic automatycznie prosi aplikację banku o zatwierdzenie, bez pytania o kod.

wskazówka

Alias jest powiązany z konkretnym klientem w Twoim systemie — to Ty decydujesz, jaki identyfikator wpisujesz do alias.value. Najczęściej jest to wewnętrzne ID użytkownika (np. UUID), tak żebyś łatwo mógł później odszukać aliasy konkretnego klienta.

Część 1. Rejestracja nowego aliasu

Rejestracja to rozszerzenie zwykłej transakcji BLIK Level 0 — obok kodu BLIK dołączasz obiekt alias, w którym mówisz Paymentic, pod jakim identyfikatorem zapamiętać płatnika.

Krok 1. Utwórz transakcję BLIK Level 0

Tak samo jak w BLIK Level 0 — podajesz dane klienta oraz paymentMethod: "BLIK" i paymentChannel: "blik-level0":

POST https://api.paymentic.com/v1_2/payment/points/{pointId}/transactions

{
  "amount": "53.23",
  "currency": "PLN",
  "title": "Zakup w sklep.pl",
  "customer": {
    "name": "Jan Kowalski",
    "email": "[email protected]",
    "ip": "83.12.45.210",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
  },
  "paymentMethod": "BLIK",
  "paymentChannel": "blik-level0"
}

Z odpowiedzi zapamiętaj data.id — to identyfikator transakcji potrzebny w kolejnym kroku.

Krok 2. Prześlij kod BLIK wraz z zaproszeniem do rejestracji aliasu

Do standardowego requesta BLIK Level 0 dokładasz obiekt alias:

POST https://api.paymentic.com/v1_2/payment/points/{pointId}/transactions/{transactionId}/blik

{
  "type": "CODE",
  "code": "777651",
  "alias": {
    "value": "9a453733-b088-4ee1-89ac-ed42d9c97e51",
    "label": "[email protected]"
  }
}

Pola obiektu alias:

Pole	Typ	Wymagane	Max długość	Opis
value	string	Tak	64	Identyfikator aliasu po Twojej stronie. Najczęściej wewnętrzne ID użytkownika (UUID, numer klienta itd.).
label	string	Nie	35	Etykieta widoczna dla klienta w aplikacji bankowej przy potwierdzeniu rejestracji aliasu. Np. zamaskowany e-mail.
appId	string	Nie	64	Identyfikator aplikacji/urządzenia — przydatny, gdy jeden klient może mieć kilka aliasów (np. desktop + mobile).

Label zobaczy klient

alias.label pojawia się w aplikacji bankowej klienta jako opis zapamiętywanej płatności. Nie wrzucaj tam danych wrażliwych ani technicznych identyfikatorów — klient ma zobaczyć coś, po czym pozna sklep i siebie (np. częściowo zamaskowany e-mail, imię + 4 cyfry numeru klienta).

Krok 3. Odbierz webhooki

Po zatwierdzeniu płatności w aplikacji banku klient zobaczy dodatkowy ekran zgody na rejestrację aliasu. W zależności od tego, co wybierze, Paymentic wyśle Ci następujące webhooki:

1. PAYMENT.TRANSACTION_BLIK_STATUS_CHANGED — status po stronie BLIK-a (np. BLIK_AUTHORIZED). Wysyłany tylko jeśli masz zasubskrybowane to zdarzenie w panelu.
2. PAYMENT.BLIK_ALIAS_STATUS_CHANGED — tylko jeśli klient potwierdził aktywację aliasu w aplikacji banku. Status: ACTIVE.
3. PAYMENT.TRANSACTION_STATUS_CHANGED — finalny status transakcji (PAID lub FAILED). Zawsze.

Brak BLIK_ALIAS_STATUS_CHANGED to normalna sytuacja

Jeśli klient odrzuci ekran zgody w aplikacji banku, sama płatność i tak się powiedzie — dostaniesz TRANSACTION_STATUS_CHANGED: PAID, ale nie dostaniesz BLIK_ALIAS_STATUS_CHANGED. To oznacza, że alias nie został utworzony i przy kolejnych zakupach klient musi znów wpisać kod BLIK.

Nie pokazuj przycisku "Zapłać One Click" na samej podstawie udanej transakcji — zrób to dopiero po odebraniu BLIK_ALIAS_STATUS_CHANGED ze statusem ACTIVE.

Szczegóły webhooków: TRANSACTION_BLIK_STATUS_CHANGED, TRANSACTION_STATUS_CHANGED, BLIK_ALIAS_STATUS_CHANGED.

Część 2. Płatność istniejącym aliasem

Gdy klient ma już aktywny alias (odebrałeś webhook BLIK_ALIAS_STATUS_CHANGED ze statusem ACTIVE), kolejną płatność możesz wykonać bez pytania o kod BLIK.

Krok 1. Utwórz transakcję BLIK Level 0

Identycznie jak przy rejestracji — ta sama struktura requesta, te same wymagane pola klienta.

Krok 2. Wyślij request aliasowy

Zamiast kodu BLIK podajesz w body type: "ALIAS" i obiekt alias z wartością zapamiętanego aliasu:

POST https://api.paymentic.com/v1_2/payment/points/{pointId}/transactions/{transactionId}/blik

{
  "type": "ALIAS",
  "alias": {
    "value": "9a453733-b088-4ee1-89ac-ed42d9c97e51"
  }
}

Kilka aliasów o tym samym value

Jeden klient może mieć kilka aliasów pod tą samą wartością (np. zarejestrowanych z różnych urządzeń). W takim przypadku musisz dodatkowo podać alias.appId, żeby jednoznacznie wskazać, którego aliasu użyć. Jeśli tego nie zrobisz, API zwróci błąd BLIK_ALIAS_NOT_UNIQUE z listą dostępnych aliasów — wtedy pokaż klientowi listę do wyboru.

Krok 3. Odbierz webhooki

Tak jak przy zwykłej transakcji BLIK Level 0:

• PAYMENT.TRANSACTION_BLIK_STATUS_CHANGED — status po stronie BLIK-a. Wysyłany tylko jeśli masz zasubskrybowane to zdarzenie w panelu.
• PAYMENT.TRANSACTION_STATUS_CHANGED — finalny status (PAID/FAILED). Zawsze.

Dodatkowy webhook BLIK_ALIAS_STATUS_CHANGED przy płatności aliasem nie jest wysyłany — chyba że zmienia się status samego aliasu (np. klient wycofał zgodę w aplikacji banku → UNREGISTERED).

Cykl życia aliasu

Status	Znaczenie
CREATED	Alias został zainicjowany po stronie Paymentic, czekamy na potwierdzenie klienta w aplikacji banku.
ACTIVE	Alias aktywny — można nim płacić bez kodu BLIK.
UNREGISTERED	Klient odrzucił rejestrację lub wycofał zgodę w aplikacji banku. Aliasu nie można już użyć.
EXPIRED	Upłynął czas ważności aliasu (expiresAt). Aliasu nie można już użyć.

wskazówka

Zanim wyświetlisz klientowi przycisk "Zapłać One Click", sprawdź po swojej stronie, czy alias ma status ACTIVE i expiresAt leży w przyszłości. Unikniesz niepotrzebnego requestu zakończonego błędem.

Obsługa błędów

Najczęstsze błędy przy płatności aliasem:

Kod	Kiedy	Co zrobić w UI
BLIK_ALIAS_NOT_FOUND	Alias o podanej wartości nie istnieje lub nie jest aktywny.	Pokaż klasyczne pole na kod BLIK i oznacz alias jako nieaktywny w swojej bazie.
BLIK_ALIAS_NOT_UNIQUE	Kilka aliasów o tym samym value — brakuje appId.	Pokaż listę aliasów z odpowiedzi błędu (pola appLabel) i daj klientowi wybrać.

Pozostałe błędy (np. BLIK_CUSTOMER_DECLINED, BLIK_INSUFFICIENT_FUNDS) działają identycznie jak w BLIK Level 0.

Testowanie

W sandboxie:

• Do rejestracji aliasu używaj dowolnego kodu zaczynającego się od 777 + 3 losowe cyfry.
• Płatność aliasem nie wymaga kodu — wyślij request z type: "ALIAS" i alias.value uzyskanym wcześniej w odpowiedzi na rejestrację.
• Dla konkretnych statusów aliasu (UNREGISTERED, EXPIRED) — skontaktuj się ze wsparciem, dostępne są dedykowane scenariusze testowe.

Więcej kodów testowych: Testowanie BLIK.

Dobre praktyki

• Pokazuj One Click tylko klientom z aktywnym aliasem. Przechowuj u siebie informację o statusie aliasu — nie polegaj na tym, że API "się domyśli".
• Nie trzymaj aliasów w nieskończoność. Alias ma expiresAt — po tej dacie już nie zadziała. Warto proaktywnie odświeżać (prosić klienta o nową rejestrację) na 1–2 tygodnie przed wygaśnięciem.
• Obsłuż UNREGISTERED webhookiem. Klient może wycofać zgodę w aplikacji banku w dowolnym momencie — dowiesz się o tym tylko z webhooka. Bez reakcji zobaczysz BLIK_ALIAS_NOT_FOUND przy najbliższej próbie płatności.
• Fallback do klasycznego BLIK-a. Zawsze zostaw klientowi opcję wpisania kodu BLIK ręcznie — na wypadek gdyby alias został unieważniony.

Co dalej?

• BLIK Level 0 — klasyczna płatność BLIK z kodem.
• BLIK_ALIAS_STATUS_CHANGED — struktura webhooka o zmianie statusu aliasu.
• Testowanie BLIK — kody i kwoty testowe.