BLIK Level 0

BLIK Level 0 pozwala klientowi wprowadzić 6-cyfrowy kod BLIK bezpośrednio w Twoim sklepie, bez przekierowywania go na stronę Paymentic ani na stronę banku. Klient zatwierdza płatność w aplikacji swojego banku, a po powrocie do sklepu widzi komunikat o zakończeniu transakcji.

W porównaniu do standardowej płatności BLIK (z przekierowaniem) Level 0 daje Ci pełną kontrolę nad UX-em checkoutu — klient nie opuszcza strony, sam decydujesz, jak wygląda pole wpisania kodu, ekran oczekiwania i komunikat sukcesu.

Jak to działa?

Krok 1. Utwórz transakcję

W pierwszym kroku utwórz transakcję z paymentMethod: "BLIK" i paymentChannel: "blik-level0". Level 0 wymaga też przekazania danych klienta — są potrzebne bankowi do oceny ryzyka transakcji:

customer.name — imię i nazwisko,
customer.email — adres e-mail,
customer.ip — adres IP klienta (ten, z którego zrobił zamówienie w Twoim sklepie),
customer.userAgent — wartość nagłówka User-Agent z przeglądarki klienta.

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

W odpowiedzi zapamiętaj data.id — będzie potrzebny w kolejnym kroku:

{
  "data": {
    "id": "3EHK-4NZ-7ES-H8P2",
    "redirectUrl": "https://pay.sandbox.paymentic.com/3EHK-4NZ-7ES-H8P2?token=...",
    "whitelabel": null
  }
}

Co z redirectUrl?

W scenariuszu BLIK Level 0 nie przekierowujesz klienta na redirectUrl — zostawiasz go w swoim checkoucie i pokazujesz pole na wpisanie kodu BLIK. redirectUrl jest w odpowiedzi jako fallback (np. gdybyś chciał dać klientowi możliwość dokończenia płatności inną metodą na stronie Paymentic).

Krok 2. Poproś klienta o kod BLIK i prześlij go do Paymentic

Pokaż klientowi pole na 6-cyfrowy kod BLIK i po jego wpisaniu wyślij go do Paymentic razem z ID utworzonej transakcji:

POST https://api.paymentic.com/v1_2/payment/points/{pointId}/transactions/{transactionId}/blik
{
    "type": "CODE",
    "code": "777592"
}

Pole type określa, w jaki sposób autoryzujesz płatność. Dla klasycznego BLIK Level 0 zawsze podajesz "CODE" (6-cyfrowy kod generowany w aplikacji banku).

Kod BLIK jest ważny tylko 2 minuty

Od momentu wygenerowania kodu w aplikacji banku klient ma ok. 2 minuty na zatwierdzenie płatności. Prześlij kod do Paymentic natychmiast po otrzymaniu go od klienta, a ekran oczekiwania pokaż z wyraźnym licznikiem czasu. Po upływie limitu bank odrzuci autoryzację i otrzymasz status BLIK_TIMEOUT.

Odpowiedź: kod przyjęty do autoryzacji

W przypadku poprawnego przesłania kodu Paymentic odpowiada HTTP 202 Accepted:

{
    "data": {
        "actionId": "01jkyr7jfcdw016wje1sc7qdys",
        "alias": null
    }
}

Pole	Opis
`actionId`	Identyfikator tej konkretnej próby autoryzacji. Pojawi się w webhooku `PAYMENT.TRANSACTION_BLIK_STATUS_CHANGED` — dzięki niemu wiążesz request z webhookiem.
`alias`	Alias BLIK (One Click). Zwrócony tylko wtedy, gdy klient przy autoryzacji zgodzi się na zapamiętanie płatności. Jeśli nie korzystasz z One Click — `null`.

Status 202 Accepted oznacza tylko, że Paymentic przyjął kod do autoryzacji, nie że płatność się powiodła. Na finalny wynik czekaj w webhooku.

Odpowiedź: kod został odrzucony

Jeśli kod jest niepoprawny, wygasł lub autoryzacja została odrzucona już na tym etapie, Paymentic zwraca błąd:

{
  "errors": [
    {
      "code": "TRANSACTION_BLIK_PROCESSING_ERROR",
      "message": "Transaction BLIK processing error.",
      "docsUrl": "https://docs.paymentic.com/errors#TRANSACTION_BLIK_PROCESSING_ERROR",
      "details": {
        "blikErrorCode": "BLIK_CODE_NOT_FOUND"
      }
    }
  ]
}

Pole details.blikErrorCode mówi, co dokładnie poszło nie tak. Najczęstsze wartości:

`blikErrorCode`	Znaczenie
`BLIK_CODE_NOT_FOUND`	Kod nie został znaleziony (klient wpisał nieistniejący kod).
`BLIK_CODE_EXPIRED`	Kod wygasł (minęły 2 minuty od wygenerowania).
`BLIK_CUSTOMER_DECLINED`	Klient odrzucił płatność w aplikacji banku.
`BLIK_SYSTEM_DECLINED`	Bank odrzucił płatność (np. blokada środków, ryzyko).
`BLIK_INSUFFICIENT_FUNDS`	Za mało środków na koncie klienta.
`BLIK_CUSTOMER_LIMIT`	Klient przekroczył dzienny/tygodniowy limit transakcyjny.
`BLIK_TIMEOUT`	Klient nie zdążył potwierdzić transakcji w aplikacji banku.

W UI sklepu warto pokazać czytelny komunikat zależny od kodu — np. "Kod wygasł, wygeneruj nowy" dla BLIK_CODE_EXPIRED lub "Brak środków na koncie" dla BLIK_INSUFFICIENT_FUNDS.

Krok 3. Odbierz webhooki o wyniku autoryzacji

Po wysłaniu kodu Paymentic wyśle Ci dwa webhooki:

PAYMENT.TRANSACTION_BLIK_STATUS_CHANGED — szczegółowy status po stronie BLIK-a (np. BLIK_AUTHORIZED, BLIK_CUSTOMER_DECLINED). Przychodzi zwykle jako pierwszy.
PAYMENT.TRANSACTION_STATUS_CHANGED — finalny status transakcji (PAID, FAILED). To jest ten webhook, na podstawie którego finalizujesz zamówienie.

Szczegóły obu webhooków:

wskazówka

Dopóki nie przyjdzie webhook TRANSACTION_STATUS_CHANGED ze statusem PAID — nie realizuj zamówienia. Status BLIK_AUTHORIZED z pierwszego webhooka potwierdza tylko zatwierdzenie po stronie klienta, ale transakcja może jeszcze zakończyć się niepowodzeniem.

Dobre praktyki

Nie pozwól na dwukrotne kliknięcie "Zapłać" — po wysłaniu kodu do Paymentic zablokuj przycisk i pokaż ekran oczekiwania. Ponowne wysłanie tego samego kodu zakończy się błędem (kod jest jednorazowy).
Pokazuj licznik czasu — klient musi wiedzieć, ile ma na zatwierdzenie w aplikacji banku.
Obsłuż sytuację, w której klient zamyka stronę w trakcie oczekiwania — status zamówienia i tak przyjdzie webhookiem, więc wysyłka/realizacja nie ucierpi.
Waliduj kod po swojej stronie zanim wyślesz — 6 cyfr, tylko cyfry. Zaoszczędzi to jeden round-trip do API.
Loguj actionId — ułatwi powiązanie problemów klienta z konkretną próbą autoryzacji przy wsparciu.

Testowanie

Sandbox Paymentic przyjmuje dowolny kod zaczynający się od 777 + 3 losowe cyfry (np. 777256) jako poprawny. Do testów konkretnych scenariuszy błędów (np. BLIK_INSUFFICIENT_FUNDS, BLIK_TIMEOUT) użyj dedykowanych kodów i kwot — pełna lista: Testowanie BLIK.

Co dalej?

Testowanie BLIK — kody i kwoty wywołujące konkretne statusy w sandboxie.
Statusy transakcji — pełny cykl życia transakcji i diagram stanów.
TRANSACTION_BLIK_STATUS_CHANGED — struktura webhooka specyficznego dla BLIK.

Jak to działa?​

Krok 1. Utwórz transakcję​

Krok 2. Poproś klienta o kod BLIK i prześlij go do Paymentic​

Odpowiedź: kod przyjęty do autoryzacji​

Odpowiedź: kod został odrzucony​

Krok 3. Odbierz webhooki o wyniku autoryzacji​

Dobre praktyki​

Testowanie​

Co dalej?​