BLIK

1 Wstęp

Płatność BLIK można zintegrować i autoryzować na kilka sposobów. Podstawowym sposobem autoryzacji jest kod BLIK, generowany przez kupującego w aplikacji mobilnej banku. Możliwa jest również autoryzacja poprzez token UID, pozwalający na realizację płatności one-click - bez opuszczania sklepu. Wybór sposobu autoryzacji jest uzależniony od scenariusza integracji płatności w sklepie:

  • Przekierowanie na stronę płatności BLIK – po wybraniu metody płatności BLIK i złożeniu zamówienia, kupujący zostaje przekierowany na stronę BLIK, gdzie wprowadza kod autoryzacyjny BLIK, a następnie potwierdza płatność w aplikacji mobilnej banku. Integracja ogranicza się do standardowej obsługi pay-by-link.
  • Płatność transparentna kodem autoryzacyjnym BLIK – kupujący wprowadza kod autoryzacyjny BLIK jeszcze na stronie sklepu, a po złożeniu zamówienia potwierdza płatność w aplikacji mobilnej banku. Integracja wymaga obsługi wprowadzania kodu autoryzacyjnego BLIK na stronie sklepu. W zamian kupujący otrzymuje prostszy i bezpieczniejszy proces autoryzacji płatności, bez konieczności przekierowania poza sklep.
  • Płatność transparentna tokenem UID – kupujący autoryzuje płatność jednym kliknięciem na stronie sklepu. Potwierdzenie płatności w aplikacji mobilnej banku nie musi być konieczne. Wybór tej usługi wymaga pełnej implementacji: procesu rejestracji tokenów po stronie sklepu, płatności tokenem oraz obsługi wprowadzania kodu autoryzacyjnego BLIK. W rezultacie kupujący otrzyma możliwość zarówno płatności jednym kliknięciem, jak i kodem autoryzacyjnym BLIK.
Usługa płatności tokenem UID, nie jest usługą domyślnie dostępną i wymaga spełnienia określonych wymagań oraz przejścia odpowiednio procesu boarding’u. Dlatego przed przystąpieniem do integracji skontaktuj się ze swoim opiekunem handlowym w PayU.
Wszystkie usługi BLIK poza opcją Przekierowanie na stronę płatności BLIK wymagają specjalnej konfiguracji punktu płatności (POS) ze strony PayU. Konfiguracja pozwalająca na „Płatność transparentną kodem autoryzacyjnym BLIK” oraz „Płatność transparentną tokenem UID” nie jest kompatybilna z opcją „Przekierowanie na stronę płatności BLIK” i wymaga obsługi na osobnym punkcie płatności.

2 Scenariusze integracji

2.1 Płatność z przekierowaniem na stronę BLIK

Zlecenie zamówienia z przekierowaniem na stronę płatności BLIK:

  1. Kupujący wybiera metodę płatności BLIK.
  2. Sklep uwierzytelnia się w PayU poprzez pobranie tokenu OAuth.
  3. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  4. PayU rejestruje transakcje w BLIK i zwraca OrderCreateResponse do sklepu z identyfikatorem utworzonego zamówienia.
  5. Sklep przekierowuje kupującego na stronę płatności BLIK.
  6. Kupujący wpisuje kod autoryzacyjny BLIK.
  7. Do aplikacji mobilnej banku kupującego, z której został wygenerowany kod autoryzacyjny BLIK, BLIK przesyła powiadomienie o konieczności autoryzacji płatności.
  8. Kupujący autoryzuje płatność w aplikacji mobilnej banku.
  9. Kupujący zostaje powiadomiony o statusie transakcji i zostaje przekierowany na stronę sklepu.

2.2 Płatność z wykorzystaniem strony płatności PayU

Zlecenie zamówienia z wykorzystaniem strony płatności PayU:

  1. Sklep uwierzytelnia się w PayU poprzez pobranie tokenu OAuth.
  2. Kupujący zostaje przekierowany na stronę płatności PayU.
  3. Kupujący wybiera metodę płatności BLIK.
  4. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  5. PayU rejestruje transakcje w BLIK i zwraca do sklepu OrderCreateResponse z identyfikatorem utworzonego zamówienia.
  6. Kupujący zostaje przekierowany na stronę płatności BLIK.
  7. Kupujący wpisuje kod autoryzacyjny BLIK.
  8. Do aplikacji mobilnej banku kupującego, z której został wygenerowany kod autoryzacyjny BLIK, BLIK przesyła powiadomienie o konieczności autoryzacji płatności.
  9. Kupujący autoryzuje płatność w aplikacji mobilnej banku.
  10. Kupujący dostaje powiadomienie o statusie tranasakcji i zostaje przekierowany na stronę sklepu.

2.3 Płatność kodem autoryzacyjnym BLIK

Podczas składania zamówienia klient ma możliwość wprowadzenia kodu autoryzacyjnego BLIK na stronie sklepu. Sklep powinien zapewnić realizację podstawowych scenariuszy obsługi:

Zlecenie zamówienia dla transparentnej płatności kodem autoryzacyjnym BLIK:

  1. Sklep prezentuje pole do wprowadzenia kodu autoryzacyjnego BLIK.
  2. Kupujący generuje kod autoryzacyjny BLIK w aplikacji mobilnej banku, a następnie wprowadza go na stronie sklepu.
  3. Sklep rozpoczyna realizację płatności, uwierzytelniając się w PayU poprzez pobranie tokenu OAuth.
  4. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  5. PayU rejestruje transakcję w BLIK i zwraca do sklepu OrderCreateResponse z identyfikatorem utworzonego zamówienia.
  6. Sklep wyświetla kupującemu stosowne informacje.
  7. Do aplikacji mobilnej banku kupującego, z której został wygenerowany kod autoryzacyjny BLIK, BLIK przesyła powiadomienie o konieczności autoryzacji płatności.
  8. Kupujący autoryzuje płatność w aplikacji mobilnej banku.
  9. Sklep otrzymuje powiadomienie o autoryzacji płatności.

Nieudane zlecenie zamówienia dla transparentnej płatności kodem autoryzacyjnym BLIK – niepoprawny kod BLIK:

  1. Sklep prezentuje pole do wprowadzenia kodu autoryzacyjnego BLIK.
  2. Kupujący generuje kod autoryzacyjny BLIK w aplikacji mobilnej banku, a następnie wprowadza go na stronie sklepu.
  3. Sklep rozpoczyna realizację płatności, uwierzytelniając się w PayU poprzez pobieranie tokenu OAuth.
  4. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  5. PayU rejestruje transakcje w BLIK i otrzymuje informację o niepoprawnym kodzie BLIK.
  6. PayU zwraca OrderCreteResponse z odpowiednim kodem błędu oraz z identyfikatorem utworzonego zamówienia.
  7. Sklep wyświetla kupującemu informację o błędzie.

2.4 Płatność tokenem UID

Przed wyświetleniem dostępnych metod płatności sklep pobiera instrumenty płatnicze i sprawdza, czy kupujący posiada token UID.

Jeśli kupujący posiada token UID, domyślnie prezentowaną w sklepie usługą dla metody płatności BLIK powinna być płatność tokenem UID. Dodatkowo, na stronie sklepu należy umożliwić kupującemu opcjonalne wprowadzenie kodu autoryzacyjnego BLIK – ta opcja jest niezbędna do prawidłowego działania usługi.

Token UID umożliwia autoryzację płatności poprzez przypisanie konkretnej aplikacji mobilnej kupującego do tokenu. Kiedy kupujący wybiera płatność tokenem UID, BLIK wysyła powiadomienie do skojarzonej z tokenem aplikacji mobilnej, w której kupujący autoryzuje płatność. Jeżeli kupujący nie może potwierdzić płatności w aplikacji mobilnej, z którą pierwotnie został powiązany token UID, wybiera opcję wprowadzenia kodu autoryzacyjnego BLIK – dzięki temu może kontynuować proces płatności.

Wprowadzenie kodu autoryzacyjnego BLIK z innej aplikacji mobilnej banku niż ta, z którą pierwotnie został powiązany token UID, skutkować będzie przypisaniem kolejnej aplikacji mobilnej banku do tokenu. Lista bankowych aplikacji mobilnych, przypisanych do tokenu UID kupującego, jest zwracana podczas pobierania instrumentów płatniczych. Jeśli kupujący ma przypisaną więcej niż jedną bankową aplikację mobilną, sklep jest zobowiązany wyświetlić ich listę w ramach usługi płatności tokenem UID. To niezbędne, aby klient wiedział, w której aplikacji mobilnej banku musi autoryzować płatność.

UWAGA! W poprzedniej wersji tego procesu, informacja o przypisaniu więcej niż jednej bankowej aplikacji mobilnej do tokenu UID była przesyłana do sklepu w odpowiedzi (OrderCreateResponse) zakończonej błędem. W ramach tej odpowiedzi sklep otrzymywał pełną listę bankowych aplikacji mobilnych przypisanych do tokenu UID. W celu realizacji zamówienia sklep wysyłał nowy OrderCreateRequest z ustawioną informacją o wybranej przez kupującego aplikacji mobilnej banku.

Rejestracja tokenu UID wymaga zapisania przez kupującego na etapie autoryzacji płatności w aplikacji mobilnej banku. Rejestracja tokenu odbywa się zawsze w kontekście autoryzacji kodem BLIK, dzięki czemu token kojarzony jest z aplikacją mobilną banku, z której kod BLIK został wygenerowany.

Wyrejestrowanie tokenu UID odbywa się na żądanie kupującego w aplikacji mobilnej banku. Token zostanie usunięty w momencie usunięcia wszystkich jego powiązań z bankowymi aplikacjami mobilnymi.

Płacący tokenem UID może płacić BLIK bez konieczności potwierdzania płatności w aplikacji mobilnej banku. O szczegóły tego rozwiązania pytaj swojego opiekuna handlowego w PayU.

Zlecenie zamówienia dla transparentnej płatności kodem autoryzacyjnym BLIK z rejestracją tokenu UID:

  1. Sklep uwierzytelnia się w PayU, w kontekście kupującego pobierając token OAuth.
  2. Sklep wysyła żądanie pobrania instrumentów płatniczych z otrzymanym od PayU tokenem OAuth.
  3. PayU nie zwraca tokenu UID.
  4. Sklep prezentuje płatność kodem autoryzacyjnym BLIK jako domyślną usługę w ramach metody płatności BLIK.
  5. Kupujący opłaca zamówienie wprowadzając kod autoryzacyjny BLIK z aplikacji mobilnej banku.
  6. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  7. PayU rejestruje w BLIK transakcję razem z żądaniem utworzenia tokenu UID, a następnie zwraca do sklepu OrderCreateResponse z identyfikatorem utworzonego zamówienia.
  8. Sklep wyświetla kupującemu stosowne informacje.
  9. BLIK przesyła powiadomienie o konieczności autoryzacji płatności do bankowej aplikacji mobilnej, która została przypisana do tokenu UID podczas jego rejestracji.
  10. Kupujący autoryzuje płatność w aplikacji mobilnej banku i zapisuje token UID.
  11. Sklep otrzymuje powiadomienie o autoryzacji płatności.
  12. PayU otrzymuje informację z BLIK o zapisaniu tokenu UID przez kupującego.
  13. PayU aktywuje dla kupującego token UID.

Zlecenie zamówienia dla transparentnej płatności tokenem UID:

  1. Sklep uwierzytelnia się w PayU, w kontekście kupującego pobierając token OAuth.
  2. Sklep wysyła żądanie pobrania instrumentów płatniczych dla kupującego z otrzymanym od PayU tokenem OAuth.
  3. PayU zwraca token UID, przypisany do jednej aplikacji mobilnej banku.
  4. Sklep prezentuje płatność tokenem UID jako domyślną usługę w ramach BLIK.
  5. Kupujący opłaca zamówienie wybierając płatność tokenem UID.
  6. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  7. PayU rejestruje transakcję w BLIK i zwraca do sklepu OrderCreateResponse z identyfikatorem utworzonego zamówienia.
  8. Sklep wyświetla kupującemu stosowne informacje.
  9. BLIK przesyła powiadomienie o konieczności autoryzacji płatności do bankowej aplikacji mobilnej, która została przypisana do tokenu UID podczas jego rejestracji.
  10. Kupujący autoryzuje płatność w aplikacji mobilnej banku.
  11. Sklep otrzymuje powiadomienie o autoryzacji płatności.

Zlecenie zamówienia dla transparentnej płatności tokenem UID, bez potwierdzenia przez kupującego:

  1. Sklep uwierzytelnia się w PayU, w kontekście kupującego pobierając token OAuth.
  2. Sklep wysyła żądanie pobrania instrumentów płatniczych dla kupującego z otrzymanym od PayU tokenem OAuth.
  3. PayU zwraca token UID, przypisany do jednej aplikacji mobilnej banku.
  4. Sklep prezentuje płatność tokenem UID jako domyślną usługę w ramach BLIK.
  5. Kupujący opłaca zamówienie wybierając płatność tokenem UID.
  6. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  7. PayU rejestruje transakcję w BLIK i zwraca do sklepu OrderCreateResponse z identyfikatorem utworzonego zamówienia
  8. Sklep wyświetla kupującemu stosowne informacje.
  9. Sklep otrzymuje powiadomienie o autoryzacji płatności.

Zlecenie zamówienia dla transparentnej płatności kodem autoryzacyjnym BLIK, z rejestracją tokenu UID dla kupującego posiadającego już token UID:

  1. Sklep uwierzytelnia się w PayU, w kontekście kupującego pobierając token OAuth.
  2. Sklep wysyła żądanie pobrania instrumentów płatniczych dla kupującego z otrzymanym od PayU tokenem OAuth.
  3. PayU zwraca token UID, przypisany do jednej aplikacji mobilnej banku.
  4. Sklep prezentuje płatność tokenem UID jako domyślną usługę w ramach BLIK.
  5. Kupujący wybiera opcję autoryzacji kodem BLIK, wprowadzając kod BLIK z aplikacji mobilnej banku.
  6. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  7. PayU rejestruje transakcję w BLIK razem z żądaniem powiązania kolejnej bankowej aplikacji mobilnej i zwraca do sklepu OrderCreateResponse z identyfikatorem utworzonego zamówienia.
  8. Sklep wyświetla kupującemu stosowne informacje.
  9. Do bankowej aplikacji mobilnej, w której został wygenerowany kod BLIK, BLIK przesyła prośbę o zapisanie tokenu UID, razem z powiadomieniem o konieczności autoryzacji płatności.
  10. Kupujący autoryzuje płatność w aplikacji mobilnej banku i zapisuje token UID.
  11. Sklep otrzymuje powiadomienie o autoryzacji płatności.
  12. PayU otrzymuje informację z BLIK o przypisaniu tokenu UID do kolejnej aplikacji mobilnej banku.

Zlecenie zamówienia dla transparentnej płatności tokenem UID, w przypadku, kiedy token przypisany jest do kilku bankowych aplikacji mobilnych:

  1. Sklep uwierzytelnia się w PayU, w kontekście kupującego pobierając token OAuth.
  2. Sklep wysyła żądanie pobrania instrumentów płatniczych dla kupującego z otrzymanym od PayU tokenem OAuth.
  3. PayU zwraca token UID, przypisany do jednej aplikacji mobilnej banku.
  4. Sklep prezentuje płatność tokenem UID jako domyślną usługę w ramach BLIK, razem z listą etykiet powiązanych bankowych aplikacji mobilnych.
  5. Kupujący opłaca zamówienie wybierając płatność tokenem UID dla określonej aplikacji mobilnej banku.
  6. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  7. PayU rejestruje transakcję w BLIK i zwraca do sklepu OrderCreateResponse z identyfikatorem utworzonego zamówienia.
  8. Sklep wyświetla kupującemu stosowne informacje.
  9. BLIK przesyła powiadomienie o konieczności autoryzacji płatności do bankowej aplikacji mobilnej, która została wybrana przez kupującego.
  10. Kupujący autoryzuje płatność w aplikacji mobilnej banku.
  11. Sklep otrzymuje powiadomienie o autoryzacji płatności.

Zlecenie zamówienia dla transparentnej płatności tokenem UID, w przypadku, kiedy token przypisany jest do kilku bankowych aplikacji mobilnych – poprzednia wersja procesu (problem niejednoznaczności):

  1. Sklep uwierzytelnia się w PayU, w kontekście kupującego pobierając token OAuth.
  2. Sklep wysyła żądanie pobrania instrumentów płatniczych dla kupującego z otrzymanym od PayU tokenem OAuth.
  3. PayU zwraca token UID bez listy przypisanych bankowych aplikacji mobilnych.
  4. Sklep prezentuje płatność tokenem UID jako domyślną usługę w ramach BLIK.
  5. Kupujący opłaca zamówienie wybierając płatność tokenem UID.
  6. Sklep tworzy zamówienie wysyłając OrderCreateRequest z otrzymanym od PayU tokenem OAuth.
  7. PayU rejestruje transakcję w BLIK i otrzymuje błąd niejednoznaczności – żądanie nie wskazuje, do której aplikacji mobilnej należy wysłać powiadomienie o autoryzacji.
  8. PayU zwraca OrderCreateResponse z odpowiednim kodem błędu oraz z listą bankowych aplikacji mobilnych przypisanych do użytego tokenu.
  9. Sklep wyświetla kupującemu listę dostępnych etykiet bankowych aplikacji mobilnych.
  10. Kupujący wybiera aplikację mobilną banku.
  11. Sklep tworzy nowe zamówienie, wysyłając OrderCreateRequest z informacją o wybranej aplikacji mobilnej banku.
  12. PayU rejestruje transakcję w BLIK i zwraca do sklepu OrderCreateResponse z identyfikatorem utworzonego zamówienia
  13. Sklep wyświetla kupującemu stosowne informacje.
  14. BLIK przesyła powiadomienie o konieczności autoryzacji płatności do aplikacji mobilnej banku kupującego, wybranej przez kupującego.
  15. Kupujący autoryzuje płatność w aplikacji mobilnej banku.
  16. Sklep otrzymuje powiadomienie o autoryzacji płatności.

3 Integracja API

3.1 Płatność z przekierowaniem na stronę BLIK

Realizacja płatności odbywa się poprzez utworzenie zamówienia w postaci OrderCreateRequest, w ramach integracji REST API.

Żądanie należy uwierzytelnić tokenem OAuth w trybie grant_type=client_credentials, umieszczonym w nagłówku żądania.

Utworzone żądanie powinno być zgodne z poniższymi wytycznymi:

Authorization: Bearer <token oauth dla grant_type=client_credentials>
Content-Type: application/json

Standardowe żądanie OrderCreateRequest należy rozszerzyć o sekcję payMethods:

"payMethods": {
    "payMethod": {
        "type": "PBL",
        "value": "blik"
    }
}

Odpowiedzi do żądania płatności BLIK z przekierowaniem na stronę płatności BLIK:

{
    "status": {
        "statusCode": "SUCCESS"
    },
    "redirectUri": "<adres z przekierowaniem>",
    "orderId": "<id utworzonego zamówienia>"
}

3.2 Płatność kodem autoryzacyjnym BLIK

Realizacja płatności odbywa się poprzez utworzenie zamówienia w postaci OrderCreateRequest, w ramach integracji REST API.

Żądanie należy uwierzytelnić tokenem OAuth w trybie grant_type=client_credentials, umieszczonym w nagłówku żądania.

Utworzone żądanie powinno być zgodne z poniższymi wytycznymi:

Authorization: Bearer <token oauth dla grant_type=client_credentials>
Content-Type: application/json

Standardowe żądanie OrderCreateRequest należy rozszerzyć o sekcje buyer i payMethods:

"buyer": {
    "email": "<adres email kupującego>"
},
"payMethods": {
    "payMethod": {
        "type": "BLIK_AUTHORIZATION_CODE",
        "value": "<kod autoryzacyjny BLIK>"
    }
}
Sekcja Parametr Wymagany Format Opis
payMethod value Tak Number: 6 cyfr Kod autoryzacyjny BLIK

Starsze warianty, których wsparcie będzie wygaszane w przyszłości:

"payMethods": {
    "payMethod": {
        "type": "PBL",
        "value": "blik",
        "authorizationCode": "<kod autoryzacyjny BLIK>",
    }
}
"payMethods": {
    "payMethod": {
        "type": "BLIK_TOKEN",
        "authorizationCode": "<kod autoryzacyjny BLIK>",
    }
}

Odpowiedzi do żądania płatności kodem autoryzacyjnym BLIK:

{
    "status": {
        "statusCode": "SUCCESS"
    },
    "orderId": "<id utworzonego zamówienia>"
}
{
    "status": {
        "statusCode": "<kod grupy błędów>",
        "codeLiteral": "<kod błędu>",
        "statusDesc": "<opis błędu>"
    },
    "orderId": "<id utworzonego zamówienia>”
}
Status Http Status code / Code literal Opis
400 ERROR_AUTHORIZATION_CODE /
AUTH_CODE_EXPIRED
Kod autoryzacyjny wygasł.
ERROR_AUTHORIZATION_CODE /
AUTH_CODE_EXCEEDED
Limit dla kodu autoryzacyjnego został przekroczony.
ERROR_AUTHORIZATION_CODE /
AUTH_CODE_CANCEL
Kod autoryzacyjny został anulowany.
ERROR_AUTHORIZATION_CODE /
AUTH_CODE_USED
Kod autoryzacyjny był już wykorzystany.
ERROR_AUTHORIZATION_CODE /
AUTH_CODE_INVALID
Niepoprawny kod autoryzacyjny.
ERROR_VALUE_INVALID /
INVALID_BLIK_CODE
Niepoprawny składniowo kod autoryzacyjny BLIK. Kod autoryzacyjny BLIK powinien składać się z 6 cyfr.
ERROR_VALUE_INVALID /
INVALID_AUTHORIZATION_CODE_USAGE
Pole authorizationCode nie może zostać użyte w tym kontekście.
ERROR_VALUE_INVALID /
INVALID_ALIAS_LABEL_PROPOSAL_USAGE
Pole aliasLabelProposal nie może być użyte podczas płatności tokenem.
ERROR_VALUE_INVALID /
INVALID_RECOMMENDED_AUTH_LEVEL_USAGE
Pole recommendedAuthLevel nie może zostać użyte w tym kontekście.
ERROR_VALUE_INVALID /
INVALID_APP_KEY_USAGE
Pole appKey nie może zostać użyte w tym kontekście.
ERROR_VALUE_MISSING /
MISSING_AUTHORIZATION_CODE
Błąd walidacji, kod autoryzacyjny wymagany.
ERROR_VALUE_MISSING /
INVALID_CURRENCY_CODE
Niepoprawny kod waluty. Obsługiwana waluta: PLN.
ERROR_VALUE_MISSING /
MISSING_BUYER_EMAIL
Błąd walidacji, brakuje pola email w sekcji buyer.

3.3 Płatność kodem autoryzacyjnym BLIK z rejestracją tokenu UID

Realizacja płatności odbywa się poprzez utworzenie zamówienia w postaci OrderCreateRequest, w ramach integracji REST API.

Żądanie należy uwierzytelnić tokenem OAuth w trybie grant_type=trusted_merchant, umieszczonym w nagłówku żądania.

Utworzone żądanie powinno być zgodne z poniższymi wytycznymi:

Authorization: Bearer <token oauth dla grant_type=trusted_merchant>
Content-Type: application/json

Standardowe żądanie OrderCreateRequest należy rozszerzyć o sekcje buyer i payMethods:

"buyer": {
    "extCustomerId": "<id kupującego w systemie merchant'a>",
    "email": "<adres email kupującego>"
},
"payMethods": {
    "payMethod": {
        "type": "BLIK_AUTHORIZATION_CODE",
        "value": "<kod autoryzacyjny BLIK>",
        "blikData": {
            "aliasLabelProposal":"<propozycja etykiety nadana przez merchant’a>",
            "register": true
        }
    }
}
Sekcja Parametr Wymagany Format Opis
buyer extCustomerId Tak Id kupującego w systemie merchant'a, w ramach, którego zostanie utworzony alias.

Ten sam extCustomerId musi być użyty przy pobieraniu tokenu oauth.
email Tak Adres e-mail kupującego.
payMethod value Tak Number: 6 cyfr Kod autoryzacyjny BLIK.
blikData aliasLabelProposal Nie String: 35 znaków Propozycja nazwy etykiety aliasu skojarzonego z daną aplikacją mobilną.

Pole to może być użyte wyłącznie podczas rejestracji tokenu.
registerTokenValue Tak String: 50 znaków Wartość tokenu UID nadana przez merchant'a.

Pole to może być użyte wyłącznie podczas rejestracji tokenu UID.
register Tak Boolean: true, false Flaga ustawiona na true określa, że wysłane zostanie żądanie rejestracji aliasu. Flaga ustawiona na false skutkować będzie płatnością kodem autoryzacyjnym T6 bez rejestracji tokenu.

Starsze warianty, których wsparcie będzie wygaszane w przyszłości:

"buyer": {
    "extCustomerId": "<id kupującego w systemie merchant'a>",
    "email": "<adres email kupującego>"
},
"payMethods": {
    "payMethod": {
        "type": "BLIK_TOKEN",
        "authorizationCode ": "<kod autoryzacyjny BLIK>",
        "blikData": {
            "register":true
        }
    }
}

Odpowiedzi do żądania płatności kodem autoryzacyjnym BLIK:

{
    "status": {
        "statusCode": "SUCCESS"
    },
    "orderId": "<id utworzonego zamówienia>"
}
{
    "status": {
        "statusCode": "<kod grupy błędów>",
        "codeLiteral": "<kod błędu>",
        "statusDesc": "<opis błędu>"
    },
    "orderId": "<id utworzonego zamówienia>”,
    "blikData": { <dane specyficzne zależne od określonego błędu> }
}
Status Http Status code / Code literal Opis
400 BUSINESS_ERROR /
TOKEN_PAYMENT_NOT_ALLOWED
Proces płatności tokenem wymaga dodatkowych uzgodnień i konfiguracji.
ERROR_AUTHORIZATION_CODE /
AUTH_CODE_EXPIRED
Kod autoryzacyjny wygasł.
ERROR_AUTHORIZATION_CODE /
AUTH_CODE_LIMIT_EXCEEDED
Limit dla kodu autoryzacyjnego został przekroczony.
ERROR_AUTHORIZATION_CODE /
AUTH_CODE_CANCEL
Kod autoryzacyjny został anulowany.
ERROR_AUTHORIZATION_CODE /
AUTH_CODE_USED
Kod autoryzacyjny był już wykorzystany.
ERROR_AUTHORIZATION_CODE /
AUTH_CODE_INVALID
Niepoprawny kod autoryzacyjny.
ERROR_VALUE_MISSING /
MISSING_AUTHORIZATION_CODE
Błąd walidacji, kod autoryzacyjny BLIK wymagany do autoryzacji.
ERROR_VALUE_INVALID /
INVALID_BLIK_CODE
Niepoprawny składniowo kod autoryzacyjny BLIK. Kod autoryzacyjny BLIK powinien składać się z 6 cyfr.
ERROR_VALUE_INVALID /
INVALID_AUTHORIZATION_CODE_USAGE
Pole authorizationCode nie może zostać użyte w tym kontekście.
ERROR_VALUE_INVALID /
INVALID_RECOMMENDED_AUTH_LEVEL_USAGE
Pole recommendedAuthLevel nie może zostać użyte w tym kontekście.
ERROR_VALUE_INVALID /
INVALID_APP_KEY_USAGE
Pole appKey nie może zostać użyte w tym kontekście.
ERROR_VALUE_MISSING /
INVALID_CURRENCY_CODE
Niepoprawny kod waluty. Obsługiwana waluta: PLN.
ERROR_VALUE_MISSING /
MISSING_BUYER_EMAIL
Błąd walidacji, brakuje pola email w sekcji buyer.
ERROR_VALUE_MISSING /
MISSING_BUYER_EXT_CUSTOMER_ID
Błąd walidacji, brakuje pola extCustomerId w sekcji buyer.
ERROR_TOKEN /
AUTH_TOKEN_EXISTS
Użytkownik extCustomerId posiada już token płatniczy o innej wartości. Kiedy użytkownik posiada inny aktywny token, należy go pobrać za pośrednictwem paymethods. Jeżeli użytkownik posiada inny token, który nie został zapisany, w odpowiedzi w komunikacie błędu w obiekcie blikData pojawi się tablica tokens z wartością tokenu:
"tokens":[
  {
    "value":"<wartość tokena>",
    "type":"<typ tokena>"
  }
]
                                
ERROR_TOKEN /
AUTH_TOKEN_NOT_ACTIVE
Użyty token płatniczy nie został zapisany przez użytkownika.

3.4 Płatność tokenem UID

Realizacja płatności odbywa się poprzez utworzenie zamówienia w postaci OrderCreateRequest, w ramach integracji REST API.

Żądanie należy uwierzytelnić tokenem OAuth w trybie grant_type=trusted_merchant, umieszczonym w nagłówku żądania.

Utworzone żądanie powinno być zgodne z poniższymi wytycznymi:

Authorization: Bearer <token oauth dla grant_type=trusted_merchant>
Content-Type: application/json

Standardowe żądanie OrderCreateRequest należy rozszerzyć o sekcje buyer i payMethods:

"buyer": {
    "extCustomerId": "<id kupującego w systemie merchant'a>",
    "email": "<adres email kupującego>"
},
"payMethods": {
    "payMethod": {
        "type": "BLIK_TOKEN",
        "value": "<wartość tokenu, który zostanie użyty do autoryzacji>",
        "blikData": {
            "appKey":"<id danego przypisania aplikacji bankowej>",
            "recommendedAuthLevel":"<NO_CONFIRMATION|REQUIRED_CONFIRMATION>",
        }
    }
}
Sekcja Parametr Wymagany Format Opis
buyer extCustomerId Tak Identyfikator kupującego w systemie merchant'a w ramach, którego zostanie utworzony alias.

Ten sam extCustomerId musi być użyty przy pobieraniu tokenu oauth.
email Tak Adres e-mail kupującego.
payMethod value Tak String: 64 znaków Wartość tokena UID, która zostanie użyta do autoryzacji, pobrana za pomocą usługi payMethods
blikData appKey Tak String: 20 znaków Identyfikator wybranego przez kupującego powiązania aplikacji bankowej, w ramach, której odbywać się będzie autoryzacja transakcji.

W przypadku poprzedniej wersji procesu, w ramach której merchant otrzymywał błąd dotyczący niejednoznaczności AUTH_TOKEN_NONUNIQUE, pole to jest nie obowiązkowe. Pole jest wypełniane wartością blikData/alternatives/appKey, zwróconą z komunikatem błędu.
recommendedAuthLevel Nie Możliwe wartości:
  • NO_CONFIRMATION,
  • REQUIRED_CONFIRMATION.
Proponowany poziom autoryzacji transakcji, gdzie NO_CONFIRMATION oznacza brak konieczności potwierdzenia transakcji przez kupującego w aplikacji mobilnej banku.

Wykorzystanie tego parametru wymaga podpisania odpowiedniego aneksu oraz spełnienie określonych wymagań compliance. O więcej informacji pytaj swojego opiekuna handlowego w PayU.

Odpowiedzi do żądania płatności kodem autoryzacyjnym BLIK:

{
    "status": {
        "statusCode": "SUCCESS"
    },
    "orderId": "<id utworzonego zamówienia>"
}
{
    "status": {
        "statusCode": "<kod grupy błędów>",
        "codeLiteral": "<kod błędu>",
        "statusDesc": "<opis błędu>"
    },
    "orderId": "<id utworzonego zamówienia>",
    "blikData": { <dane specyficzne zależne od określonego błędu> }
}
Status Http Status code / Code literal Opis
400 ERROR_TOKEN /
AUTH_CODE_NOT_FOUND
Podany token płatniczy nie istnieje.
ERROR_TOKEN /
AUTH_TOKEN_NONUNIQUE
Użyty token płatniczy jest przypisany do kilku aplikacji bankowych. Wymagane jest podanie określonej aplikacji bankowej, do której zostanie wysłane prośba o autoryzację przez kupującego.
Razem z błędem, w OrderCreateResponse, w sekcji blikData zostanie zwrócona aktualna lista aplikacji bankowych przypisanych do tokenu:
"alternatives":[
  {
    "appKey":"<id przypisania>",
    "appLabel":"<etykieta>"
  },
  {
    "appKey":"<id przypisania>",
    "appLabel":"<etykieta>"
 }
]
              
                                
ERROR_VALUE_MISSING /
INVALID_CURRENCY_CODE
Niepoprawny kod waluty. Obsługiwana waluta: PLN.
ERROR_VALUE_MISSING /
MISSING_APPKEY
Błąd walidacji, brakuje identyfikatora powiązanej aplikacji bankowej.
ERROR_VALUE_MISSING /
MISSING_BUYER_EMAIL
Błąd walidacji, brakuje pola email w sekcji buyer.
ERROR_VALUE_MISSING /
MISSING_BUYER_EXT_CUSTOMER_ID
Błąd walidacji, brakuje pola extCustomerId w sekcji buyer.
ERROR_VALUE_MISSING /
MISSING_AUTHORIZATION_CODE_OR_TOKEN
Błąd walidacji, dane autoryzacyjne wymagane – brakuje tokenu.
ERROR_VALUE_INVALID /
INVALID_ALIAS_LABEL_PROPOSAL_USAGE
Pole aliasLabelProposal nie może być użyte podczas płatności tokenem.
ERROR_VALUE_INVALID /
AMBIGUOUS_AUTHORIZATION_USAGE
Podano dwa instrumenty do autoryzacji; w celu realizacji płatność tokenem powinno być wypełnione wyłącznie pole value, w którym umieszczony zostanie token.
BUSINESS_ERROR /
RECOMMENDED_AUTH_LEVEL_NOT_ALLOWED
Opcja wyboru poziomu autoryzacji nie została udostępniona merchantowi. Należy skontaktować się z działem obsługi klienta.
BUSINESS_ERROR /
RECOMMENDED_AUTH_LEVEL_USAGE_NOT_ALLOWED
Wykorzystanie RecommendedAuthLevel wymaga podpisania odpowiedniego aneksu oraz spełnienie określonych wymagań compliance.

4 Usługi wspierające

W tej sekcji zawarte zostały informacje na temat usług umożliwiających prawidłowe zbudowanie i wysłanie żądania płatności BLIK.

4.1 Pobieranie tokenu OAuth

Realizacja płatności tokenem UID wymaga pobrania tokenu dla grant_type=trusted_merchant w kontekście ext_customer_id oraz email. Opis usługi uwierzytelniania znajdziesz w sekcji Uwierzytelnienie użytkownika API.

4.2 Pobieranie metod płatności

Usługa pobierania metod płatności zwraca również instrumenty płatnicze, w tym token UID. Wykorzystanie tej usługi jest niezbędne w celu poprawnej integracji procesu płatności tokenem UID. Token UID zostanie zwrócony w tablicy:

"blikTokens": [
    {
        "value": "<wartość tokenu>",
        "type": "UID",
        "brandImageUrl": "<adres url do pliku graficznego>",
        "bankApplicationReferences": [
            {
                "key": "<id przypisania danej aplikacji bankowej>",
                "label": "<etykieta przypisania danej aplikacji bankowej>"
            }
        ]
    }
]

Specyfikacja tablicy blikTokens:

Sekcja Parametr Format Opis
value String: 64 znaków Wartość tokenu.
type UID Typ tokenu.
brandImageUrl url Odnośnik do pliku graficznego na serwerze PayU, reprezentującego typ płatności.
bankApplicationReferences key String: 20 znaków Unikalny klucz przypisania danej aplikacji bankowej do tokenu.
Wartość tego pola wstawiana jest w zamówieniu w polu payMethod.blikData.appKey.
label String: 35 znaków Wartość etykiety przypisania danej aplikacji bankowej do tokenu.
Lista wartości tych pól prezentowana jest kupującemu do wyboru podczas płacenia tokenem UID.

4.3 Pobieranie danych transakcji

Szczegóły danych transakcji do określonego zamówienia można pobrać za pomocą usługi pobrania danych transakcji.

Pole resultCode i sekcja blik mogą się nie pojawić jeśli obsługa danej transakcji nie została jeszcze zakończona:

{
    "transactions": [
        {
            "payMethod": {
                "value": "blik"
            },
            "paymentFlow": "<sposób obsługi płatności>",
            "resultCode": "<kod rezultatu np. REG_ERROR_AUTH_CODE_EXPIRED>".
            "blik”: {
                "txRef": "<id transakcji nadany przez BLIK>",
                "extTxRef": "<id transakcji nadany przez PayU>"
            }
        }
    ]
}

Opis parametrów, otrzymanych w odpowiedzi na zapytanie o dane transakcji BLIK dla danego zamówienia:

Sekcja Parametr Format Opis
paymentFlow
  • BLIK_PBL
  • BLIK_AUTHORIZATION_CODE
  • BLIK_AUTHORIZATION_CODE_​_WITH_UID_TOKEN_REGISTERING
  • BLIK_UID_TOKEN
Definiuje sposób obsługi płatności.
resultCode Wartość słownikowa Kod rezultatu obsługi transakcji.
payMethod value blik Typ metody płatności.
blik txRef String Id transakcji nadany przez system BLIK.
extTxRef String Id transakcji nadany przez PayU.

Specyfikacja pola resultCode, którego wartością jest jeden z kodów rezultatu obsługi transakcji BLIK:

resultCode codeDescription
REG_ERROR_TOKEN_NONUNIQUE Wykorzystany token płatniczy jest przypisany do kilku urządzeń / aplikacji bankowych. Wymagane jest podanie w polu appKey identyfikatora konkretnej aplikacji bankowej przypisanej do tokenu płatniczego. Lista dostępnych alternatyw (aplikacji bankowych) zwrócona jest w odpowiedzi na obsługę OrderCreateRequest. Listę dostępnych alternatyw można pobrać również za pomocą metody paymethods, o ile merchant wykorzystuje obsługę niednoznaczności.
REG_ERROR_TOKEN_NOT_FOUND Wykorzystany token płatniczy nie istnieje. Wymagana ponowna rejestracja tokenu z podaniem kodu autoryzacyjnego BLIK.
AUT_ERROR_TOKEN_DECLINED Odmowa realizacji transakcji dla przesłanego tokenu ze względów bezpieczeństwa. Wymagana ponowna rejestracja tokenu z podaniem kodu autoryzacyjnego BLIK.
REG_ERROR_AUTH_CODE_EXPIRED Kod autoryzacyjny BLIK wygasł.
REG_ERROR_AUTH_CODE_LIMIT_EXCEEDED Limit dla kodu autoryzacyjnego BLIK został przekroczony.
REG_ERROR_AUTH_CODE_CANCELED Kod autoryzacyjny BLIK został anulowany.
REG_ERROR_AUTH_CODE_USED Kod autoryzacyjny BLIK był już wykorzystany.
REG_ERROR_AUTH_CODE_INVALID Niepoprawny kod autoryzacyjny BLIK.
REG_ERROR_USER_APP_NOT_ACTIVE Aplikacja bankowa użytkownika nie została poprawnie zarejestrowana. W celu realizacji transakcji wymagany kontakt z bankiem.
REG_ERROR_ISSUER_TEMPORARY Bank wybrany przez użytkownika do realizacji płatności ma przerwę techniczną lub tymczasowe problemy. Użytkownik powinien spróbować zrealizować płatność później lub wybrać inny bank.
REG_ERROR_ISSUER_TOKEN_NOT_SUPPORTED Wybrany bank w ramach realizowanej płatności nie obsługuje tokenów.
REG_ERROR_BLIK_INTERNAL Błąd wewnętrzny po stronie BLIK. Użytkownik może spróbować ponownie zlecić realizację nowej transakcji.
AUT_ERROR_BLIK_INTERNAL Błąd wewnętrzny po stronie BLIK. Użytkownik może spróbować ponownie zlecić realizację nowej transakcji.
REG_ERROR_VALIDATION Odmowa rozpoczęcia realizacji transakcji ze względu na niepoprawne dane w żądaniu. Przed ponowieniem płatności należy poprawić dane.
REG_ERROR_INTERNAL Błąd wewnętrzny po stronie PayU. Użytkownik może spróbować ponownie zlecić realizację nowej transakcji, w przypadku nieudanej kolejnej próby należy skontaktować się z PayU.
AUT_ERROR_INTERNAL Błąd wewnętrzny po stronie PayU. Użytkownik może spróbować ponownie zlecić realizację nowej transakcji. W przypadku nieudanej kolejnej próby należy skontaktować się z PayU.
AUT_ERROR_USER_TIMEOUT Płatność nie została potwierdzona na czas w aplikacji banku.
AUT_ERROR_LIMIT_EXCEEDED Płatność odrzucona ze względu na przekroczenie limitu.
AUT_ERROR_INSUFFICIENT_FUNDS Płatność odrzucona ze względu na brak środków.
AUT_ERROR_USER_DECLINED Płatność odrzucona w aplikacji bankowej przez użytkownika.
AUT_ERROR_ISSUER_DECLINED Płatność odrzucona przez bank.
AUT_ERROR_BLIK_DECLINED Płatność odrzucona przez BLIK.
OK Transakcja zakończona sukcesem – rozliczona lub nieodebrana przez merchant'a.
REG_ERROR_ANTIFRAUD_DECLINED Transakcja odrzucona na etapie rejestracji przez system antyfraudowy.
AUT_ERROR_ANTIFRAUD_DECLINED Transakcja odrzucona na etapie autoryzacji przez system antyfraudowy.
AUT_ERROR_NO_AUTHORIZATION Nie otrzymano autoryzacji, transakcja została anulowana.

5 Sandbox

Integrację płatności BLIK możesz przetestować w środowisku testowym sandbox. W tej sekcji zawarto testowe kody autoryzacyjne, prefiksy tokenów UID do symulacji określonych typów płatności, jak również przykłady żądań płatności.

Żądania zostały uzupełnione przykładowymi danymi, które możesz zmieniać posiłkując się specyfikacją przedstawioną wcześniej w tym dokumencie.

Lista kodów autoryzacyjnych BLIK symulujących określone zachowanie (obecna wersja usługi):

  • 200201 - pozytywna autoryzacja z rejestracją tokenu,
  • 500500 - negatywna autoryzacja,
  • 777xxx - pozytywna autoryzacja bez rejestracji tokenu,
  • 700701 - kod autoryzacyjny BLIK wygasł,
  • 700702 - kod autoryzacyjny BLIK został anulowany,
  • 700703 - kod autoryzacyjny BLIK został już użyty.

Niektóre kody zmieniają swoje przeznaczenie w czasie. Opis ich funkcji dla poprzedniej wersji usługi zawarty został w poniższej liście:

  • 777xxx - pozytywna autoryzacja z rejestracją tokenu.

Lista prefiksów tokenów UID, symulujących określone zachowanie:

  • SIMULATE_ALIAS_AMBIGUITY - rejestracja tokenu dla aktualnej wersji obsługi, w której lista przypisanych bankowych aplikacji mobilnych zwracana jest w usłudze pobierania metod płatności.
  • SIMULATE_ALIAS_NON_UNIQUE - symulacja problemu z niejednoznacznością - poprzednia wersja procesu.

Aby zasymulować określone zachowanie, podczas płatności tokenem, w polu payMethod.value należy podać wybrany prefiks oraz losowy ciąg znaków.

Przed wysłaniem żądania testowego należy wygenerować token OAuth (korzystając z adresu url https://secure.snd.payu.com/pl/standard/user/oauth/authorize) dla używanego punktu sprzedaży (POS).

5.1 Płatność z przekierowaniem na stronę płatności BLIK

Przykład żądania testowego płatności z przekierowaniem na stronę płatności BLIK:

curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
-H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
-H "Content-Type: application/json" \
-d '{
    "currencyCode": "PLN",
    "totalAmount": "21000",
    "description": "Transakcja testowa",
    "notifyUrl": "https://your.eshop.com/notify",
    "customerIp": "127.0.0.1",
    "merchantPosId": "300746",
    "products": [
        {
            "name": "Wireless Mouse for Laptop",
            "unitPrice": "21000",
            "quantity": "1"
        }
    ],
    "payMethods": {
        "payMethod": {
            "type": "PBL",
            "value": "blik"
        }
    }
}'

5.2 Płatność kodem autoryzacyjnym BLIK

Przykład żądania testowego płatności BLIK z kodem autoryzacyjnym:

curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
-H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
-H "Content-Type: application/json" \
-d '{
    "currencyCode": "PLN",
    "totalAmount": "21000",
    "description": "Transakcja testowa",
    "notifyUrl": "https://your.eshop.com/notify",
    "customerIp": "127.0.0.1",
    "merchantPosId": "300746",
    "products": [
        {
            "name": "Wireless Mouse for Laptop",
            "unitPrice": "21000",
            "quantity": "1"
        }
    ],
    "payMethods": {
        "payMethod": {
            "type": "BLIK_AUTHORIZATION_CODE",
            "value": "777654"
        }
    }
}'

Odpowiedź na żądanie zależy od kodu autoryzacyjnego BLIK użytego w polu authorizationCode. Do symulacji możesz użyć jednego z kodów testowych.

5.3 Płatność tokenem UID

Przykład żądania testowego rejestracji tokenu UID:

curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
-H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
-H "Content-Type: application/json" \
-d '{
    "currencyCode": "PLN",
    "totalAmount": "21000",
    "description": "Transakcja testowa",
    "notifyUrl": "https://your.eshop.com/notify",
    "customerIp": "127.0.0.1",
    "merchantPosId": "300746",
    "products": [
        {
            "name": "Wireless Mouse for Laptop",
            "unitPrice": "21000",
            "quantity": "1"
        }
    ],
    "buyer": {
        "extCustomerId": "customer123",
        "email": "john.doe@email.com"
    },
    "payMethods": {
        "payMethod": {
            "type": "BLIK_AUTHORIZATION_CODE",
            "value": "777123",
            "blikData": {
                "aliasLabelProposal":"token for eshop.pl",
                "register": true
            }
        }
    }
}

Odpowiedź na żądanie zależy od kodu autoryzacyjnego BLIK użytego w polu authorizationCode. Do symulacji możesz użyć jednego z kodów testowych.

Przykład żądania testowego płatności BLIK z tokenem UID:

curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
-H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
-H "Content-Type: application/json" \
-d '{
    "currencyCode": "PLN",
    "totalAmount": "21000",
    "description": "Transakcja testowa",
    "notifyUrl": "https://your.eshop.com/notify",
    "customerIp": "127.0.0.1",
    "merchantPosId": "300746",
    "products": [
        {
            "name": "Wireless Mouse for Laptop",
            "unitPrice": "21000",
            "quantity": "1"
        }
    ],
    "buyer": {
        "extCustomerId": "customer123",
        "email": "john.doe@email.com"

    },
    "payMethods": {
        "payMethod": {
            "type": "BLIK_TOKEN",
            "value": "SIMULATE_ALIAS_AMBIGUITY-5690871207003",
            "blikData": {
                "appKey": "22222662",
                "recommendedAuthLevel": "NO_CONFIRMATION",
            }
        }
    }
}'