BLIK OneClick

1 BLIK OneClick

Płatność BLIK można skonfigurować na kilka sposobów. Najprostszym jest przekierowanie: klient wpisuje kod na stronie BLIK, po czym potwierdza płatność w aplikacji mobilnej swojego banku. Płatność BLIK może być jednak szybsza i bardziej wygodna, dzięki transparentnej integracji z PayU.

Testowe scenariusze użycia:

Scenariusz 1.

Płatność BLIK level 0 (transparentna płatność kodem T6)

Sześciocyfrowy kod T6, którym klient rozpoczyna płatność, nie musi być wpisywany na stronie BLIK - sprzedawca może go pobierać już na swojej stronie, przyjmując zamówienie.

  1. OAuth authorize (pobrany access_token)
  2. BLIK OCR code (utworzony order z płatnością T6)
  3. Order Retrieve (sprawdzenie statusu ordera)

Scenariusz 2.

Płatność BLIK level 0 z rejestracją tokenu (transparentna płatność kodem T6)

Za każdym razem, kiedy klient poda kod T6, sprzedawca może wysyłać żądanie rejestracji tokenu BLIK. Pojawi się wtedy dodatkowa opcja zapisania płatności BLIK, dostępna przy potwierdzaniu tranksacji w aplikacji mobilnej banku (na stronie sprzedawcy nie są potrzebne dodatkowe kontrolki).

  1. OAuth authorize (pobrany access_token)
  2. BLIK OCR - token register by payu (utworzony order z płatnością T6 + rejestracja tokenu)
  3. system PayU automatycznie aktywuje token
  4. Order Retrieve (sprawdzanie statusu ordera)
  5. PayMethods Retrieve (pobranie instrumentów płatniczych - pojawia się token BLIK)

Scenariusz 3.

Płatność BLIK OneClick (transparentna płatność tokenem)

Jeśli przy poprzedniej transakcji klient skorzystał z opcji zapisania płatności BLIK, może teraz zapłacić jednym kliknięciem, bez wpisywania kodu.

  1. BLIK OCR - pay with token (płatność samym tokenem)
  2. Order Retrieve (sprawdzenie statusu ordera)
  3. PayMethods Retrieve (pobranie instrumentów płatniczych - pojawia się token BLIK)

Scenariusz 4.

Obsługa niejednoznaczności (transparentna płatność z więcej niż jednym tokenem)

Klient może mieć konta w kilku bankach i używać BLIK w każdym z nich. Jeśli sprzedawca zapisze token BLIK z jednego banku, to przy próbie kolejnej płatności BLIK z innego banku powstanie niejednoznaczność. PayU umożliwia obsługę takiego wyjątku i pozwala klientowi na późniejszy wybór spośród wielu zapisanych płatności, jednym kliknięciem.

Dany scenariusz testowy dzieli się na dwa etapy. Podczas kroków 1-3 tworzona jest niejednoznaczność. Kroki 4-6 symulują płatność OneClick podczas wystąpienia niejednoznaczności.

  1. OAuth authorize (pobieranie access token)
  2. PayMethods Retrieve (pobieranie listy metod płatności; brak tokenu dla danego klienta)
  3. BLIK OCR - register nonunique token (rejestracja tokenu niejednoznacznego)
  4. PayMethods Retrieve (pobieranie listy metod płatności; w odpowiedzi pojawia się token)
  5. BLIK OCR - pay with token (płatność tokenem niejednoznacznym)
  6. BLIK OCR - pay with nonunique token (płatność tokenem niejednoznacznym z wprowadzoną alternatywą)

Kolekcja scenariuszy w Postman do testowania:

Możliwe jest przetestowanie usługi na środowisku sandbox. W tym celu można skorzystać z kolekcji scenariuszy w Postman.

Przy testowaniu w zależności od użytego kodu t6(authorizationCode) można uzyskać:
  • 777123 - autoryzację pozytywną,
  • 500500 - autoryzację negatywną.

2 Przykłady wykonania scenariuszy

2.1 Płatność blik level 0

Pobranie tokena OAuth'owego:

                curl -X POST https://secure.snd.payu.com/pl/standard/oauth/authorize \
                 -d 'grant_type=trusted_merchant&client_id=300746&client_secret=2ee86a66e5d97e3fadc400c9f19b065d&email=johndoe@gmail.com&ext_customer_id=JohnDoe'
                 
            

Specyfikacja parametrów żądania pobrania tokenu OAuth

Parametr Opis
email Adres e-mail kupującego
ext_customer_id Identyfikator kupującego używany w systemie klienta

Przykład odpowiedzi:

                {
                    "access_token": "f24bbf9b-30f0-4460-864f-aaadc07d1e34",
                    "token_type": "bearer",
                    "refresh_token": "b7a4375a-d4fc-41a0-a380-a9dd8c2e9193",
                    "expires_in": 43199,
                    "grant_type": "trusted_merchant"
                }
            

Przykład zamówienia z tokenem OAuth'owym:

BLIK oparty jest na standardowej integracji z PayU poprzez REST API opisanej na: Tworzenie nowego zamówienia. Rozszerzeniem jest pole payMethods dodane do komunikatu OrderCreateRequest.

                   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",
                                "authorizationCode": "777123"
                            }
                        }
                   }'
                

Specyfikacja parametrów żądania OrderCreateRequest

Parametr Opis
payMethod/type Typ metody płatności.
payMethod/value Symbol typu płatności.
payMethod/authorizationCode Dla transparentnej integracji metody płatności BLIK: pozwala pobrać 6-cyfrowy kod na stronie sklepu bez przekierowania na stronę BLIK. Zobacz więcej o transparentnej integracji.

Po dokonaniu płatności, PayU wysyła powiadomienie na adres podany w zamówieniu w parametrze notifyUrl. Szczegóły dotyczące powiadomień zawarto w rozdziale Powiadomienia.

Przykładowa odpowiedź wykonanego zamówienia:

                {
                    "orderId": "LDTD3S2WWC181109GUEST000P01",
                    "status": {
                        "statusCode": "SUCCESS"
                    }
                }
            

W odpowiedzi zwracane jest orderId które jest identyfikatorem danego zamówienia. Jest ono używane przy żądaniu Order Retrieve.

2.2 Transparentna płatność BLIK z rejestracją tokenu

Przykład zamówienia:

Aby udostępnić możliwość zapisania tokenu w celu późniejszych płatności OneClick, należy rozszerzyć payMethod o pole blikData z flagą "register": true.

                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": "Testowa transakcja",
                     "notifyUrl": "https://your.eshop.com/notify",
                     "customerIp": "127.0.0.1",
                     "merchantPosId": "300746",
                     "buyer": {
                         "extCustomerId": "JohnDoe",
                         "email": "johndoe@gmail.com"
                     },
                     "products": [
                         {
                             "name": "Wireless Mouse for Laptop",
                             "unitPrice": "21000",
                             "quantity": "1"
                         }
                     ],
                     "payMethods": {
                         "payMethod": {
                             "type": "BLIK_TOKEN",
                             "authorizationCode": "777123",
                             "blikData": {
                                 "register":true
                             }
                         }
                     }
                }'
            
Specyfikacja parametrów żądania OCR:
Parametr Opis
payMethod/blikData/register Pozwala na zapisanie tokenu w celu późniejszego użycia. Możliwe wartości:
  • true - tylko w tym przypadku user zobaczy opcje zapisu tokenu
  • false

PayMethods Retrieve (pobranie metod płatności)

Poniższe żądanie pobiera instrumenty płatnicze - pojawia się token blikowy:
                curl -X GET https://secure.snd.payu.com/api/v2_1/paymethods \
                 -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47"
            
Między innymi zwracany jest token blikowy:
            {
                "blikTokens": [
                    {
                        "value": "TOKB_nuGYkknycEp3NDWAN2hh1c7FLnXseaLX",
                        "type": "UID",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_blik.png"
                    }
                ],
                "cardTokens": [],
                "pexTokens": [],
                "payByLinks": [
                    {
                        "value": "blik",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_blik.png",
                        "name": "BLIK",
                        "status": "ENABLED"
                    },
                    {
                        "value": "p",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_p.png",
                        "name": "Płacę z iPKO",
                        "status": "ENABLED"
                    },
                    {
                        "value": "m",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_m.png",
                        "name": "mTransfer",
                        "status": "ENABLED"
                    },
                    ... //pojawiają się pozostałe dostępne metody płatności
                    {
                        "value": "c",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_c.png",
                        "name": "Płatność online kartą płatniczą",
                        "status": "ENABLED"
                    }
                ],
                "status": {
                    "statusCode": "SUCCESS"
                }
            }
            

Specyfikacja parametrów odpowiedzi żądania PayMethods Retrieve:

W przypadku blikTokens:

Parametr Opis
value Wartość tokenu
type Typ tokenu
brandImageUrl Odnośnik do pliku graficznego na serwerze PayU reprezentującego typ płatności.

2.3 Transparentna płatność tokenem

Przykład transparentnej płatności tokenem:

W polu payMethod wczytywany jest token wygenerowany przy pierwszej transakcji. Płacący nie musi wpisywać kodu T6.

                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",
                     "buyer": {
                         "extCustomerId": "JohnDoe",
                         "email": "johndoe@gmail.com"
                     },
                     "products": [
                         {
                             "name": "Wireless Mouse for Laptop",
                             "unitPrice": "21000",
                             "quantity": "1"
                         }
                     ],
                     "payMethods": {
                         "payMethod": {
                             "type": "BLIK_TOKEN",
                             "value": "TOKB_nuGYkknycEp3NDWAN2hh1c7FLnXseaLX"
                         }
                     }
                }'
            

Specyfikacja parametrów żądania OrderCreateRequest

Parametr Opis
payMethod/value Wartość tokenu BLIK

2.4 Scenariusz obsługi niejednoznaczności

Rejestracja tokenu niejednoznacznego

               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",
                    "buyer": {
                        "extCustomerId": "JohnDoe",
                        "email": "johndoe@gmail.com"
                    },
                    "products": [
                        {
                            "name": "Wireless Mouse for Laptop",
                            "unitPrice": "21000",
                            "quantity": "1"
                        }
                    ],
                    "payMethods": {
                        "payMethod": {
                            "type": "BLIK_TOKEN",
                            "value": "SIMULATE_ALIAS_NON_UNIQUE",
                            "authorizationCode": "777123",
                            "blikData": {
                                "register":true
                            }
                        }
                    }
                }'
            
Parametr Opis
payMethod/blikData/register Pozwala na zapisanie tokenu w celu późniejszego użycia. Możliwe wartości:
  • true - tylko w tym przypadku user zobaczy opcje zapisu tokenu
  • false
payMethod/value Unikalny identyfikator pozwalajacy na testowanie niejednoznaczności. W celach testowych należy jako wartość tego parametru podać "SIMULATE_ALIAS_NON_UNIQUE" + losowy ciąg liczb i/lub znaków.
SIMULATE_ALIAS_NON_UNIQUE jest stałą, dzięki której możliwe jest wygenerowanie niejednoznaczności na sandbox. Na środowisku produkcyjnym niejednoznaczność powstaje przy płatności po użyciu, przez Użytkownika, kodu T6 z różnych aplikacji bankowych.

Płatność tokenem niejednoznacznym z wprowadzoną alternatywą

Przykład żądania stworzenia nowego ordera razem z wprowadzoną alternatywą.

                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",
                        "buyer": {
                            "extCustomerId": "JohnDoe",
                            "email": "johndoe@gmail.com"
                        },
                        "products": [
                            {
                                "name": "Wireless Mouse for Laptop",
                                "unitPrice": "21000",
                                "quantity": "1"
                            }
                        ],
                        "payMethods": {
                            "payMethod": {
                                "type": "BLIK_TOKEN",
                                "value": "SIMULATE_ALIAS_NON_UNIQUE",
                                "blikData": {
                                    "appKey":"930872"
                                }
                            }
                        }
                    }'
            

Parametr Opis
payMethod/blikData/appKey Opcjonalny klucz aplikacji mobilnej BLIK'a.

3 Statusy błędów

Jeżeli przesłane zostanie niepoprawne żądanie, to w odpowiedzi zawarty będzie status, kod oraz opis błędu wg poniższej tabeli.

Kody statusów błędów
HTTP status StatusCode/
CodeLiteral
Opis
400
ERROR_TOKEN/
AUTH_TOKEN_NONUNIQUE
Wykorzystany token płatniczy jest przypisany do kilku urządzeń/aplikacji bankowych. Wymagane jest podanie alternatywy dla wykorzystywanego tokenu płatniczego. W odpowiedzi pojawia się lista dostępnych alternatyw: OrderCreateResponse:
{
    "blikData":{
        "alternatives":[
            {
            "appKey":"alternative key",
            "appLabel":"alternative label"
            }
        ]
    }
}
400 ERROR_TOKEN/
AUTH_TOKEN_NOT_FOUND
Podany token płatniczy nie istnieje.
400 ERROR_TOKEN/
AUTH_TOKEN_EXISTS
Użytkownik posiada już token płatniczy o innej wartości. W przypadku, w którym użytkownik posiada inny aktywny token, należy go pobrać za pośrednictwem payMethods. W przypadku, w którym użytkownik posiada inny token, który nie został aktywowany w odpowiedzi pojawi się jego wartość:
{
    "blikData":{
        "tokens":[
            {
            "value":"token value",
            "type":"token type"
            }
        ]
    }
}
400 ERROR_TOKEN/
AUTH_TOKEN_NOT_ACTIVE
Użyty token płatniczy nie został zapisany przez użytkownika.
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_LIMIT_EXPIRED
Kod autoryzacyjny wygasł.
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_EXCEEDED
Limit dla kodu autoryzacyjnego został przekroczony.
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_CANCEL
Kod autoryzacyjny został anulowany.
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_USED
Kod autoryzacyjny był już wykorzystany,
400 ERROR_AUTHORIZATION_CODE/
AUTH_CODE_INVALID
Niepoprawny kod autoryzacyjny.
201* WARNING_CONTINUE_TOKEN
201* WARNING_CONTINUE_​AUTHORIZATION_CODE
400 ERROR_VALUE_MISSING/
MISSING_AUTHORIZATION_CODE.
Błąd walidacji, kod autoryzacyjny wymagany.
400 ERROR_VALUE_MISSING/
MISSING_REGISTER_FLAG
Błąd walidacji, flaga rejestracji tokenu - wymagana.
400 ERROR_VALUE_MISSING/
MISSING_AUTHORIZATION_​CODE_OR_TOKEN
Błąd walidacji, dane autoryzacyjne wymagane: kod autoryzacyjny lub token.
400 ERROR_VALUE_MISSING/
INVALID_CURRENCY_CODE
Niepoprawny kod waluty. Obsługiwana waluta: PLN.
400 ERROR_VALUE_MISSING/
MISSING_BUYER
Błąd walidacji, brakuje sekcji buyer.
400 ERROR_VALUE_MISSING/
MISSING_BUYER_EMAIL
Błąd walidacji, brakuje pola email w sekcji buyer.
400 ERROR_VALUE_MISSING/
MISSING_BUYER_EXT_​CUSTOMER_ID
Błąd walidacji, brakuje pola extCustomerId w sekcji buyer.

*Do implementacji w momencie gdy PSP dostarczy zmianę po swojej stronie. Od początku merchant musi być przygotowany na przyjecie obu statusów odpowiedzi. W pierwszej fazie integracji merchant obsługuje statusy (ERROR_AUTH_TOKEN, WARNING_CONTINUE_AUTH_TOKEN) w ten sam sposób.