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.

Do każdego z tych rozwiązań (płatność po przekierowaniu na eblik.pl (paymentwall) lub dzięki transparentnej integracji) wymagany jest odrębny POS. Integracja transaparentna w wersji z synchronicznymi odpowiedziami i/lub z rejestracją tokenu BLIK wymaga specjalnej konfiguracji.

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

Niejednoznaczność w wersji 1.0 jest przestarzała. Poniższy opis służy jako referencja do istniejących integracji. Rekomendujemy używanie niejednoznaczności 2.0.

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

Informacje dotyczące testowania usługi zawarte zostały w sekcji Sandbox.

BLIK OneClick wymaga autoryzacji OAuth w trybie dostępu "trusted_merchant". Dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.

Pobranie tokena OAuth'owego:

                curl -X POST https://secure.snd.payu.com/pl/standard/oauth/authorize \
                 -d 'grant_type=client_credentials&client_id=300746&client_secret=2ee86a66e5d97e3fadc400c9f19b065d'
                 
            

Przykład odpowiedzi:

                {
                    "access_token": "f24bbf9b-30f0-4460-864f-aaadc07d1e34",
                    "token_type": "bearer",
                    "expires_in": 43199,
                    "grant_type": " client_credentials"
                }
            

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

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.

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

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:

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

PayMethods Retrieve (pobranie metod płatności)

                curl -X GET https://secure.snd.payu.com/api/v2_1/paymethods \
                 -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47"
            

            {
                "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:

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

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

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

Wprowadzenie

Pierwotna wersja obsługi niejednoznaczności zakładała, że o konieczności wyboru aplikacji bankowej sprzedawca dowiadywał się dopiero w momencie otrzymania błędu w odpowiedzi do transakcji (OrderCreateResponse). Wymuszało to ponowne zlecenie zamówienia wraz z wyborem aplikacji, na którą zostanie wysłane powiadomienie o autoryzacji transakcji.

Niejednoznaczność 2.0 odwraca ten proces. Niezbędne informacje wymagane w celu wybrania aplikacji bankowej są pobierane razem z metodami płatności. Lista dostępnych aplikacji bankowych została zawarta w nowej sekcji bankApplicationReferences.

Merchant dla którego ustawiono obsługę niejednoznaczności 2.0 zobowiązany jest do przesyłania parametru appKey dla każdej płatności tokenem UID.

Rejestracja tokena UID w trybie niejednoznaczności

Poniższy przykład przedstawia żądanie transakcji, podczas której kupujący zostanie poinformowany o możliwości zapamiętania aplikacji dla danego sklepu (zakomunikowane jest to przez parametr blikData.register z wartością true). Kolejne płatności w danym sklepie będą wymagały jedynie potwierdzenia w aplikacji banku bez konieczności podawania 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": "SIMULATE_ALIAS_AMBIGUITY-5690871207003",
                        "authorizationCode": "777123",
                        "blikData": {
                            "register":true
                        }
                    }
                }
            }'
                
            

Przykład pozytywnej odpowiedzi:

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

Pobieranie metod płatności

Przy niejednoznaczności 2.0 po pobraniu metod płatności, w sekcji bankApplicationReferences zwracana jest lista zapisanych aplikacji bankowych, na które można przesłać notyfikację w celu potwierdzenia transakcji.

Żądanie pobrania metod płatności:

                curl -X GET https://secure.snd.payu.com/api/v2_1/paymethods \
                -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47"
            

Przykład odpowiedzi pobrania metod płatności:

            {
                "blikTokens": [
                    {
                        "value": "SIMULATE_ALIAS_AMBIGUITY-5690871207003",
                        "type": "UID",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_blik.png",
                        "bankApplicationReferences": [
                            {
                                "key": "11111",
                                "label": "te...c6@de...et"
                            },
                            {
                                "key": "22222",
                                "label": "eg...7p@de...et"
                            }
                        ]                
                    }
                ],
                "cardTokens": [],
                "pexTokens": [],
                "payByLinks": [
                    {
                        "value": "blik",
                        "brandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_blik.png",
                        "name": "BLIK",
                        "status": "ENABLED",
                        "minAmount": "100",
                        "maxAmount": "99999999"
                    },
                    ... //pojawiają się pozostałe dostępne metody płatności
                ],
                "status": {
                    "statusCode": "SUCCESS"
                }
            }
            
            

Płatność tokenem

W celu realizacji płatności tokenem należy wybrać jedną z zapisanych aplikacji bankowych z listy bankApplicationReferences. Następnie wartość pola key należy podać w polu payMethod.blikData.appKey.

Przykład żądania stworzenia nowego zamówienia:

            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": "Płatność testowa z tokenem UID",
                "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_AMBIGUITY-5690871207003",
                        "blikData": {
                            "appKey":"22222"
                        }
                    }
                }
            }'
                    
            

Przykład pozytywnej odpowiedzi:

            {
                "status": {
                    "statusCode": "SUCCESS"
                },
                "orderId": "6R2SV2MDQD220425GUEST000P01"
            }
                
            

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

{
    "blikData":{
        "alternatives":[
            {
            "appKey":"alternative key1",
            "appLabel":"alternative label1"
            },
            {
            "appKey":"alternative key2",
            "appLabel":"alternative label2"
            }
        ]
    }
}

{
    "blikData":{
        "tokens":[
            {
            "value":"token value",
            "type":"token type"
            }
        ]
    }
}

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

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

Kody służące do symulacji transakcji z niepoprawnym kodem T6