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.
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).
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.
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.
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.
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" }
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.
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 |
---|---|
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" }
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 } } } }'
Parametr | Opis |
---|---|
payMethod/blikData/register | Pozwala na zapisanie tokenu w celu późniejszego użycia. Możliwe wartości:
|
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. |
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 |
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.
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:
|
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. |
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. |
Uruchomienie procesu obsługi niejednoznaczności 2.0 wymaga konfiguracji po stronie PayU. Dlatego rozpoczynając integrację prosimy o kontakt z PayU poprzez Państwa opiekuna handlowego bądź dział obsługi klienta.
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.
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 } } } }'
Parametr | Opis |
---|---|
payMethod.type | Typ metody płatności. |
payMethod.value | Wartość tokena UID, która zostanie użyta do jego autoryzacji. W celach testowych należy jako wartość tego parametru podać "SIMULATE_ALIAS_AMBIGUITY-" + losowy ciąg liczb i/lub znaków. |
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. |
payMethod.blikData.register | Pozwala na zapisanie tokena w celu późniejszego użycia.
Możliwe wartości:
|
Przykład pozytywnej odpowiedzi:
{ "status": { "statusCode": "SUCCESS" }, "orderId": "JS8VHC92LM220425GUEST000P01" }
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" } }
Parametr | Format | Opis |
---|---|---|
blikTokens.value | String: 50 znaków | Wartość tokena UID, który zostanie użyty do autoryzacji. |
blikTokens.type | UID | Typ tokena - aktualnie wspieranym typem jest wyłącznie UID. |
blikTokens.brandImageUrl | Odnośnik do pliku graficznego na serwerze PayU reprezentującego typ płatności. | |
blikTokens.bankApplicationReferences.key | String: 20 znaków | Unikalny klucz przypisania danej aplikacji bankowej do tokena.
Przekazywany w polu payMethod.blikData.appKey
podczas realizacji płatności tokenem UID. |
blikTokens.bankApplicationReferences.label | String: 35 znaków | Etykieta wskazująca na aplikację bankową przypisaną do tokena. |
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" } } } }'
Parametr | Wymagany | Format | Opis |
---|---|---|---|
buyer.extCustomerId | Tak | Identyfikator kupującego w systemie akceptanta w ramach,
którego zostanie utworzony alias. Ten sam
extCustomerId musi być użyty przy
pobieraniu tokena oAuth. |
|
buyer.email | Tak | Adres e-mail kupującego. | |
payMethod.value | Tak | String: 50 znaków | Wartość tokena UID, która zostanie użyta do autoryzacji. |
payMethod.blikData.appKey | Tak | String: 20 znaków | Identyfikator wybranej aplikacji bankowej w ramach, której odbywać się będzie autoryzacja transakcji. Pole obowiązkowe podczas korzystania z niejednoznaczności w wersji 2.0. |
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.
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 key1", "appLabel":"alternative label1" }, { "appKey":"alternative key2", "appLabel":"alternative label2" } ] } } |
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_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/ MISSING_APPKEY |
Błąd walidacji, brakuje id przypisania danej aplikacji bankowej. |
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 . |
400 | ERROR_VALUE_INVALID/ AMBIGUOUS_AUTHORIZATION_USAGE |
Podano dwa instrumenty do autoryzacji. W celu realizacji
płatności tokenem powinno być wypełnione wyłącznie pole
value , w którym umieszczony zostanie
token. |
*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.
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ć:
Kod T6 | StatusCode | CodeLiteral |
---|---|---|
700701 | ERROR_AUTHORIZATION_CODE | AUTH_CODE_EXPIRED |
700702 | ERROR_AUTHORIZATION_CODE | AUTH_CODE_CANCEL |
700703 | ERROR_AUTHORIZATION_CODE | AUTH_CODE_USED |