Nowy standard uwierzytelniania.
Informacje znajdujące się w tym rozdziale dotyczą standardu 3DS 2 i tzw. "silnego uwierzytelnienia" (SCA). Jeżeli masz już podstawową wiedzę na ten temat, możesz przejść do rozdziału Wpływ na istniejące integracje lub Rozszerzenia API.
3DS 2 (lub "EMV 3-D Secure" - od nazwy organizacji zarządzającej nowym standardem) jest ulepszoną wersją uwierzytelnienia 3-D Secure (3DS), wdrażanego przez wydawców kart i agentów rozliczeniowych, w ramach systemów kart płatniczych np. MasterCard (MasterCard SecureCode) i Visa (Verified by Visa).
W pierwotnym standardzie 3DS użytkownik był przekierowywany na stronę wydawcy karty. Tam musiał zaakceptować transakcję, podając jednorazowe hasło z SMS (tzw. one-time password - OTP) lub potwierdzając płatność w aplikacji mobilnej swojego banku.
Nowy standard 3DS 2 pozwala na bardziej przyjazny proces płatności, czasem całkowicie pozbawiony przekierowania i dodatkowych metod uwierzytelniających.
Zmianę standardu odzwierciedla też zmiana marki usług oferowanych przez MasterCard i Visa, odpowiednio: MasterCard Identity Check i Visa Secure.
Nowa dyrektywa PSD2 (Payment Service Directive) to akt prawny, który wprowadza nakaz "silnego uwierzytelnienia" (SCA - Strong Customer Authentication) dla płatności internetowych. Dyrektywa wchodzi w życie 14 września 2019 r
Wprowadzenie PSD2 oznacza, że wszystkie płatności kartami będą wymagały 3DS 2. Transakcji zapisanymi kartami nie będzie można przetwarzać jako "one-click", a transakcje cykliczne (płatności okresowe, wykonywane przez merchanta za naszym pozwoleniem, ale bez naszego udziału) w ogóle nie będą możliwe.
Na szczęście przewidziano odstępstwa.
Silnego uwierzytelnienia będzie wymagać jedynie pierwsza płatność, rozpoczynająca subskrypcję – kolejne płatności będą z tego wymogu zwolnione.
Ustalono, że płatność będzie uważana za cykliczną, jeżeli jej kwota pozostanie niezmienna.
Jeżeli kwota płatności cyklicznej ulegnie zmianie (ma to miejsce w przypadku płatności, przy których kwota transakcji zmienia się wraz z użyciem danego produktu/usługi, np. rachunki za media, usługi telekomunikacyjne), taką transakcję uznaje się za zainicjowaną przez merchanta (MIT - Merchant Initiated Transaction) i również wyłącza z potrzeby silnego uwierzytelnienia.
W obu przypadkach, przed obciążeniem karty, wymagana jest zgoda jej właściciela.
Z przymusu silnego uwierzytelnienia wyłączone są również transakcje o niskim ryzyku. Ryzyko jest ustalane dla wydawcy karty i agenta rozliczeniowego, na podstawie średniego poziomu oszustw. Agent rozliczeniowy, wysyłając prośbę o autoryzację, może oznaczyć transakcję jako mało ryzykowną, jednak to po stronie wydawcy karty leży zaakceptowanie tej decyzji. W przypadku wątpliwości, żądanie może zostać odrzucone, a dalszy proces będzie wymagać silnego uwierzytelnienia.
Zaakceptowanie braku silnego uwierzytelnienia ze względu na niską kwotę lub niewielkie ryzyko jest zawsze decyzją wydawcy karty. Jeżeli wydawca karty uzna, że silne uwierzytelnienie jest wymagane, odmówi autoryzacji, odpowiadając konkretnym kodem błędu.
Próbę autoryzacji można ponowić, uzupełniając komunikat o wynik uwierzytelnienia za pomocą 3DS. Więcej szczegółów znajduje się w sekcji Obsługa "soft decline".
Przy 3DS 2 rozróżnia się dwa tryby uwierzytelnienia: “przeglądarkowy” ("browser") i “sdk”.
Trybu sdk można używać w aplikacjach mobilnych wyłącznie z certyfikowanym SDK, wspierającym standard 3DS 2. W przypadku PayU takie SDK będzie zawarte w gotowym rozwiązaniu PayU | Mobile.
Do wszystkich pozostałych integracji (strony internetowej wyświetlanej na komputerze lub urządzeniu mobilnym, aplikacji mobilnej używającej modułu web-view do płatności i jej uwierzytelnienia) używa się trybu przeglądarkowego.
Tryb przeglądarkowy może składać się z dwóch części: "Metody 3DS" i "Wyzwania" ("Challenge"). Przy pierwszej z nich wystawca karty może zażądać pobrania unikalnych cech urządzenia (fingerprinting) poprzez ukrytą ramkę iframe, wyświetloną w przeglądarce użytkownika. Druga część - "Challenge" – wymaga od płatnika wykonania akcji, np. wpisania hasła. Uwierzytelnienie płatności w trybie przeglądarkowym może wymagać jednej bądź obydwu opisanych części.
Strona płatności PayU będzie wspierać 3DS 2. Jeżeli jej używasz, nie musisz nic robić. Silne uwierzytelnienie (SCA) będzie dokonywane po przekierowaniu płatnika na stronę PayU.
Aby zwiększyć prawdopodobieństwo bezproblemowego uwierzytelnienia 3DS 2, możesz przekazać do PayU dodatkowe informacje (tylko w przypadku integracji REST API).
Aby zwiększyć prawdopodobieństwo bezproblemowego uwierzytelnienia 3DS 2, zalecane jest przekazanie PayU dodatkowych informacji (tylko w przypadku integracji REST API).
Dla merchantów obsługujących płatności kartą we własnej aplikacji mobilnej, PayU oferuje 3DS SDK, które może obsłużyć uwierzytelnienie 3DS 2 (bez użycia modułu web-view, wyświetlającego stronę uwierzytelniającą PayU).
Podstawowe scenariusze mogą zostać przetestowane z użyciem środowiska testowego PayU ("sandbox").
Dane kart testowych znajdują na stronie "sandbox".
O nowe pola danych, związane z 3DS 2, zostało rozszerzone wyłącznie REST API.
W celu spełnienia wymagań zawartych w standardzie 3DS 2, REST API zostało rozszerzone o nowe pola. Aby nie zakłócać istniejących integracji, dodatkowe pola nie są wymagane. Jednakże, zgodnie ze standaradem 3DS 2, niektóre pola są obowiązkowe dlatego, w przypadku gdy ich nie wyślesz, zostaną domyślnie wypełnione przez PayU.
Poniższa tabela zawiera parametry wymagane przez standard 3DS 2. Jest to minimum informacji, które oczekiwane są przy próbie uwierzytelnienia z tym protokołem. Jeżeli pola nie zostaną przez Ciebie wypełnione, PayU prześle domyślnie dane.
Rekomendujemy abyś wysyłał poniższe pola dla wszystkich transakcji, które mogą buć uwierzytelniane w standardzie 3DS 2:
payMethods.payMethod.value
ustawionym na
jedną z płatności kartowych: c, ap, jp, ma, vc,payMethods.payMethod.type
ustawionym na
CARD_TOKEN,payMethods.card
,payMethods
(w przypadku gdy na POS masz
skonfigurowaną jakąkolwiek płatność kartową).Szczegółowe opisy nowych pól możesz znaleźć w sekcji opisowej obiektu threeDsAuthentication.
Parametr | Komentarz |
---|---|
buyer.email | - |
buyer.phone | Prosimy o korzystanie z formatu +[kod kraju] [numer], np. +48 225108001 |
buyer.delivery | Wysyłane jako "adres do wysyłki" podczas uwierzytelnienia 3DS 2.
Zwróć uwagę, że pole state w obiekcie
buyer.delivery jest wymagane i jego wartość
powinna być poprawnym kodem ISO 3166-2 (np. "UT" dla Utah w USA lub
"30" dla "Wielkopolskie" w Polsce). |
threeDsAuthentication.cardholder.name | Imię i nazwisko nadrukowane na karcie. Jeżeli nie zostanie
wypełnione wartość zostanie wygenerowana z
buyer.firstName i
buyer.lastName . W przypadku braku tych
wartości, przesłana zostanie podstawiona wartość domyślna. |
threeDsAuthentication.cardholder.billingAddress | Zwróć uwagę, że pole state w obiekcie
billingAddress jest wymagane i jego wartość
powinna być poprawnym kodem ISO 3166-2 (np. "UT" dla Utah w USA lub
"30" dla "Wielkopolskie" w Polsce). |
threeDsAuthentication.browser | Jeżeli ten parametr nie zostanie wysłany i obiekt
sdk nie istnieje, to zostanie stworzony
domyślny obiekt (browser.requestIp zostanie
zmapowane na podstawie customerIp ). |
threeDsAuthentication.sdk | Musi zostać wysłany, aby uwierzytelnienie zostało przeprowadzone w trybie SDK. Ta wartość nie jest wysyłana domyśnie. Jeżeli parametr nie jest obecny, zakładany jest tryb przeglądarkowy. |
W tej sekcji znajduje się przykładowy order z minimalnymi danymi, które są wymagane przez PayU, ale zawierającymi również dane wymagane przez standard 3DS 2, które nie zostały uznane za obowiązkowe przez PayU.
curl -X POST https://secure.payu.com/api/v2_1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
"continueUrl": "http://www.payu.pl",
"customerIp": "216.72.35.5",
"merchantPosId": "145227",
"description": "Order with 3DS 2 required fields",
"currencyCode": "PLN",
"totalAmount": 300,
"products": [
{
"name": "a product",
"unitPrice": 300,
"quantity": 1
}
],
"buyer": {
"firstName": "John",
"lastName": "Doe",
"phone": "+48 555555555",
"email": "john@doe.pl",
"delivery": {
"street": "Delivery St. 1",
"postalCode": "55-033",
"city": "Delivery Town",
"state": "30",
"countryCode": "PL"
}
},
"threeDsAuthentication": {
"cardholder": {
"name": "Joe Doe",
"billingAddress": {
"street": "Billing St. 1",
"postalCode": "33-055",
"city": "Billington",
"state": "30",
"countryCode": "PL"
}
},
"browser": {
"acceptHeaders": "*/*",
"screenWidth": "1536",
"javaEnabled": false,
"timezoneOffset": "-120",
"screenHeight": "864",
"requestIP": "216.72.35.5",
"language": "en",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:81.0) Gecko/20100101 Firefox/81.0",
"colorDepth": "24"
}
}
}'
curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
-d '{
"continueUrl": "http://www.payu.pl",
"customerIp": "216.72.35.5",
"merchantPosId": "300746",
"description": "Order with 3DS 2 required fields",
"currencyCode": "PLN",
"totalAmount": 300,
"products": [
{
"name": "a product",
"unitPrice": 300,
"quantity": 1
}
],
"buyer": {
"firstName": "John",
"lastName": "Doe",
"phone": "+48 555555555",
"email": "john@doe.pl",
"delivery": {
"street": "Delivery St. 1",
"postalCode": "55033",
"city": "Delivery Town",
"state": "30",
"countryCode": "PL"
}
},
"threeDsAuthentication": {
"cardholder": {
"name": "Joe Doe",
"billingAddress": {
"street": "Billing St. 1",
"postalCode": "33055",
"city": "Billington",
"state": "30",
"countryCode": "PL"
}
},
"browser": {
"acceptHeaders": "*/*",
"screenWidth": "1536",
"javaEnabled": false,
"timezoneOffset": "-120",
"screenHeight": "864",
"requestIP": "216.72.35.5",
"language": "en",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:81.0) Gecko/20100101 Firefox/81.0",
"colorDepth": "24"
}
}
}'
Zmiany w odpowiedziach zawarte w tym podrozdziale dotyczą żądań z danymi karty
(tokenizowanymi przez PayU, tokenizowanymi przez Google Pay lub w
postaci tekstowej), zawartymi w obiekcie
payMethod
.
Istniejąca
odpowiedź
WARNING_CONTINUE_3DS została poszerzona o pola
threeDsProtocolVersion
(możliwe wartości: 3DS1 i
3DS2) i iframeAllowed
. Będzie to wskazywało, że
redirectUri
może być wyświetlona w ramce iframe.
Istnieje możliwość wykorzystania ramki iframe zamiast pełnego przekierowania.
W przypadku zainteresowania takim rozwiązaniem proszę przejść do sekcji Strona uwierzytelniająca.
Przykładowa odpowiedź:
{ "status": { "statusCode": "WARNING_CONTINUE_3DS", "severity": "WARNING" }, "redirectUri": "{redirectUri}", "iframeAllowed": true, "threeDsProtocolVersion": "3DS2", "orderId": "QK52JR2VCR201023GUEST000P01" }
redirectUri
nie będzie miało zastosowania w aplikacjach mobilnych natywnie obsługujących uwierzytelnienie
3DS 2.
Zamiast tego, w odpowiedzi zostanie zwrócony obiekt
challengeParameters
, który powinien być przekazany do aplikacji
mobilnej.
Przykładowa odpowiedź:
{ "status": { "statusCode": "SUCCESS", "statusDesc": "Request successful" }, "threeDsProtocolVersion": "3DS2", "challengeParameters": { "threeDsServerTransactionId": "0016f22b-f988-4358-b2c6-8917bba22037", "acsTransID": "d7c1ee99-9478-44a6-b1f2-391e29c6b340", "acsReferenceNumber": "3DS_LOA_ACS_201_13579", "acsSignedContent": "someBase64encodedString" }, "orderId": "JQC8TR8L4J201023GUEST000P01" }
Pobranie danych transakcji jest możliwe w momencie zakończenia bądź odrzucenia zamówienia. Szczegóły zwracanych pól opisane są w sekcji Parametry komunikaty JSON. Ta sekcja skupia się na wyjaśnieniu szczegółów odpowiedzi 3DS, na którą składają się poniższe pola:
Dla zwięzłości, poniższy opis odnosi się do odpowiedzi dla 3DS 2. 3DS 1 nadal może być sporadycznie używany do 10.2022 r., jednak na tej stronie statusy i opisy dla tej wersji są pomijane.
ECI (Electronic Commerce Indicator) wskazuje poziom uwierzytelnienia transakcji. W praktyce, informuje o odpowiedzialności w sytuacji wystąpienia oszustwa związanego z obciążeniem zwrotnym (chargeback). W przypadku próby uwierzytelnienia (attempted authentication) i pełnego uwierzytelnia (full authentication) odpowiedzialność leży po stronie wystawcy karty, w innych przypadkach odpowiedzialność ponosi merchant, przy czym:
Wartości ECI zależą od systemu karty płatniczej:
Stopień uwierzytelnienia | Visa | Mastercard |
---|---|---|
Pełne uwierzytelnienie | 5 | 2 |
Próba uwierzytelnienia | 6 | 1 |
Brak uwierzytelnienia | 7 | 0 |
Brak uwierzytelnienia, dane z 3DS zostały wysłane do systemu karty płatniczej | 4 | |
Pełne uwierzytelnienie, transakcja cykliczna | 7 |
Nie jest to pełna lista dostępnych kodów ECI, obejmuje ona jedynie wartości, które można otrzymać w danych transakcyjnych.
Nie jest to pełna lista statusów 3DS 2, obejmuje ona jedynie wartości, które można otrzymać w danych transakcyjnych.
Kod ECI nie wskazuje czy transakcja została uwierzytelniona poprzez "wyzwanie".
Aby pomóc rozróżnić czy właściciel karty został "wyzwany" przez wystawcę karty, przesyłamy dodatkowe pole, które nie jest częścią standardu 3DS 2. "Wyzwanie" może przyjąć formę, np. potwierdzenia transakcji w aplikacji mobilnej ("out of bound authentication"), konieczności wprowadzenia jednorazowego hasła (OTP, zwykle wysłane jako wiadomość SMS - "dynamic authentication") lub konieczności wprowadzenia statycznego hasła ("static authentication").
"Wyzwanie" nie musi oznaczać silnego uwierzytelnienia kupującego (SCA, wymaganego w krajach Europejskiego Obszaru Gospodarczego). Wynika to z faktu, że SCA wymaga 2FA (uwierzytelnienia dwuskładnikowego), a wystawca karty może zastosować tylko jedną metodę uwierzytelnienia. W przypadku wystawców kart z EOG, można założyć, że "wyzwanie" oznacza SCA, jednakże ta zasada nie musi dotyczyć wystawców z innych regionów.
Możliwe wartości indykatora frictionless:
Opis statusu 3DS przedstawia szczegóły odpowiedzi 3DS i jest tablicą oddzielonych przecinkami pól danych 3DS 2. Wartości elementów są opisowymi reprezentacjami kodów 3DS 2 specyficznych dla danego pola.
Elementy tablicy opisane są w poniższej tabeli. Należy pamiętać, że ze względu na dużą ilość możliwych wartości nie są one wyliczone (jednak najczęstsze kombinacje zostały omówione w sekcji poniżej). Same wartości są w większości przypadków opisami kodów określonych w standardzie 3DS 2 i zaczerpnięte zostały ze specyfikacji. Sam standard wyjaśnia znaczenie danego pola, ale nie wyjaśnia szczegółowo jakie wartości może ono przyjmować. Dlatego użycie poszczególnych wartości zależy od konkretnej implementacji. Przykładowo, potwierdzenie transakcji w aplikacji mobilnej może być przez jednego wystawcę oznaczone jako "dynamic authentication", a przez innego jako "out of bound".
Pozycja | Źródło | Komentarz |
---|---|---|
0 | wersja 3DS 2 | Określa numer wersji wiadomości (obecnie 2.1.0 lub 2.2.0). |
1 | Kanał urządzenia | Określa czy uwierzytelnienie miało miejsce w przeglądarce czy w natywne w aplikacji mobilnej. Obecnie jest to zawsze tryb przeglądarkowy ("browser flow"). |
2 | Indykator realizacji metody 3DS | Określa czy wystawca karty powiadomił o zakończeniu pobierania unikalnych cech urządzenia ("fingerprinting") poprzez ukrytą ramkę iframe wyswietlaną w przeglądarce. |
3 | Typ uwierzytelnienia | Dotyczy uwierzytelnienia z "wyzwaniem". Najczęściej spotykane wartości to "dynamic authentication" i "out of boud". Więcej informacji na temat "wyzwania" znajdziesz w sekcji Indykator frictionless. |
4 | Odrzucenie "wyzwania" | Dotyczy uwierzytelnienia z "wyzwaniem". Określa czy "wyzawanie" zostało anulowane i dlaczego. |
5 | Przyczyna zaistniałego statusu transakcji | Informuje dlaczego pole Transaction Status ma określoną wartość. |
W tej sekcji zostały zawarte najczęściej występujące opisy statusów 3DS:
//Pomyślne uwierzytelnienie właściciela karty Mastercard, przy użyciu wersji 2.1.0. //Metoda 3DS nie została zastosowana, "wyzwanie" zostało zainicjowane. "cardEciCode": "2", "card3DsStatus": "Y", "card3DsFrictionlessIndicator": "NO", "card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,dynamic authentication,no cancel indicator,no status reason"
//Pomyślne uwierzytelnienie właściciela karty Visa, przy użyciu wersji 2.2.0. //Metoda 3DS została zastosowana, "challenge" nie został zainicjowany. "cardEciCode": "5", "card3DsStatus": "Y", "card3DsFrictionlessIndicator": "YES", "card3DsStatusDescription": "MessageVersion=2.2.0,browser flow,3DS method completed,frictionless authentication,no challenge,no status reason"
//Nieuwierzytelniona transakcja, której dane 3DS zostały przekazane do Mastercard. "cardEciCode": "4", "card3DsStatus": "U", "card3DsFrictionlessIndicator": "YES", "card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,frictionless authentication,no challenge,data-only"
//Nieudane uwierzytelnienie posiadacza karty Mastercard. //Właściciel karty nie wykonał "wyzwania" i transakcja została zakończona przez wystawcę karty. "cardEciCode": "0", "card3DsStatus": "N", "card3DsFrictionlessIndicator": "NO", "card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,out of band authentication,challenge displayed - ACS timeout,timed out at ACS"
//Nieudane uwierzytelnienie posiadacza karty Visa. //Właściciel karty odrzucił "wyzwanie". "cardEciCode": "7", "card3DsStatus": "N", "card3DsFrictionlessIndicator": "NO", "card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,dynamic authentication,challenge canceled by cardholder,authentication failed"
//Nieudane uwierzytelnienie posiadacza karty Visa. //"Wyzwanie" nie zostało wyświetlone i transakcja została zakończona przez wystawcę karty. //Najczęściej, "challenge" nie zostaje wyświetlony ponieważ nie wykonano przekierowania na adres URL strony uwierzytelniającej zwrócony przez PayU. "cardEciCode": "7", "card3DsStatus": "N", "card3DsFrictionlessIndicator": "NO", "card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,dynamic authentication,challenge not displayed,timed out at ACS"
Wydawcy kart płatniczych z krajów objętych regulacją SCA, mają prawo zastosować tzw. soft decline dla płatności kartą, dla których nie nastąpiło pełne uwierzytelnienie posiadacza karty.
W przypadku jeśli nie następuje przekierowanie na stronę płatniczą PayU i używana jest tokenizacja kart, istnieją dwa sposoby obsługi soft decline dla trybu przeglądarkowego:
Należy zastosować następującą logikę:
cardResponseCode
ma wartość SSD (soft decline), wysłać ponownie order create request z polem threeDsAuthentication.challengeRequested
z wartością MANDATE.W powyższym przypadku, wartość MANDATE zmusza wydawcę do wykonania pełnego uwierzytelnienia za pomocą tzw. challenge.
WAŻNE: po wdrożeniu takiego rozwiązania, należy je zgłosić poprzez kontakt z Biurem Obsługi Klienta aby zostać wyłączonym z rozwiązania opisanego poniżej.
To rozwiązanie nie wymaga zmian w integracji związanych z obsługą kodu WARNING_CONTINUE_3DS
zwróconego w order create response,
ale należy pamiętać, że wówczas przekierowanie następować będzie dla KAŻDEJ płatności
kartą bez uwierzytelnienia, tzw. one-click, za wyjątkiem transakcji oznaczonych jako
RECURRING lub STANDARD_MERCHANT.
System PayU będzie wykorzystywać dostępne odstępstwa w zakresie 3DS 2, aby unikać przypadków SCA i utrzymać dotychczasowy standard obsługi transakcji "one-click" dla zapisanych kart.
Jeżeli jednak wystąpi soft decline transakcji, to wtedy sposób jego obsługi zależy od używanego trybu.
W przypadku trybu przeglądarkowego (płatności zainicjowane poprzez stronę internetową, z komputerów stacjonarnych bądź środowiska mobile-view), płatnik zostanie poproszony o uwierzytelnienie płatności na stronie uwierzytelniającej PayU.
Aby móc obsługiwać przypadki soft decline w trybie sdk, konieczna jest
możliwość pobrania szczegółów każdej
transakcji. Pozwala to na sprawdzenie kodu błędu, który wystąpił
przy odrzuconym żądaniu. Po wystąpieniu soft decline (pole cardResponseCode
o wartości SSD"), płatność może zostać
powtórzona jako nowa transakcja z parametrem challengeRequested
ustawionym na MANDATE.
Poniższe instrukcje dotyczą testowania przypadku kiedy Twoje konto na sandbox zostało
wykluczone z domyślnej konfiguracji (obsługa soft decline wyłaczona po stronie PayU).
Aby wykluczyć sklep z domyślnej konfiguracji skontaktuj się z nami.
podając id sklepu
którego używasz do testów.
Aby przetestować przypadek soft decline dla płatności kartą:
totalAmount
mniejszym bądź równym 300 groszom (niezależnie od waluty) aby wyłączyć płatność z
uwierzytelnienia za pomocą 3DS 2.Po przeprowadzeniu dowolnego z poniższych scenariuszy otrzymasz OrderCreateResponse ze statusem SUCCESS, a następnie notyfikację ze statusem CANCELED. Możesz sprawdzić, że przyczyną odmowy był kod SSD pobierając szczegóły transakcji.
W przypadku procesu 3DS 2 dziejącego się w przeglądarce użytkownika, cały proces uwierzytelnienia jest obsługiwany na stronie serwowanej przez PayU.
Może ona zostać wyświetlona po pełnym przekierowaniu płatnika bądź jako ramka (iframe), ukryta aż do momentu gdy wymagana będzie autoryzacja - ze szczegółami tego rozwiązania można zapoznać się w sekcji Obsługa ramki iframe
Po wyświetleniu się użytkownikowi, na stronie ukazane są informacje wstępne.
Wersja językowa wyświetlonych informacji zależy od parametru navigator.language. W przypadku braku wsparcia dla podanego języka, informacja zostanie wyświetlona w języku angielskim.
Uwaga: wersję językową można ustawić ręcznie, przez dodanie parametru
lang=[language]
(parametr używa dwuliterowego kodu językowego
ISO) do query string adresu URL strony uwierzytelniającej. Listę dostępnych
języków razem z ich kodami można znaleźć w kolumnie "Strona
uwierzytelniająca" w sekcji językowej.
W zależności od zastosowanych reguł, system PayU:
Uwaga: jeżeli próba autoryzacji bez uwierzytelnienia (nr. 1 z powyższej listy) zakończyła się przypadkiem soft decline, PayU zainicjuje "wyzwanie" i ponowi autoryzację jeżeli uwierzytelnienie się powiedzie.
W przypadku kolejnego obciążenia zapisanego tokenu z pełnym uwierzytelnieniem, nie ma potrzeby
ponownej obsługi statusu WARNING_CONTINUE_CVV dodanego do pola
continueUrl
w OrderCreateRequest.
CVV zostanie zebrane przez formularz wyświetlony na stronie uwierzytelniającej.
Uwaga: istnieje możliwość wyłączenia formularzu pobierającego CVV na stronie
uweirzytelniającej PayU i zaimplementowanie go na swojej stronie. Można to osiągnąć
przez ustwienie parametru cvv=false
w query string adresu
URL strony uwierzytelniającej.
Bez względu na wynik uwierzytelnienia, po zakończeniu procesu użytkownik zostanie przekierowany na twoją stronę (w przypadku przekierowania) w innym przypadku będziesz musiał zamknąć ramkę iframe gdy spełni swoje zadanie.
Aby dostosować stronę uwierzytelniającą do swoich potrzeb możesz użyć parametrów:
false
, ponieważ komunikat CReq może zostać wysłany tylko raz.Poniższe rozwiązanie może zostać użyte jedynie kiedy parametr iframeAllowed
zwrócony w komunikacie order create response ma wartość true.
Poniżej znajduje się przykładowy opis sposobu wyświetlenia strony uwierzytelniającej w iframe w oknie modalnym
Przykład zakłada użycie trzech elementów HTML:
<div class="modal"> <div class="modal-content"> <iframe src="redirectUri"> <!-- dokument strony uwierzytelniającej zawarty zostanie tutaj --> </iframe> </div> </div>
Nie zaleca się ustawiania atrybutu "sandbox" dla iframe. Nie możemy zagwarantować, że uwierzytelnienie przeprowadzone przez wydawców kart zadziała za każdym razem.
Jeżeli jednak zdecydujesz się na wprowadzenie dodatkowych ograniczeń do ramki iframe, należy najmniej zezwolić na wykonanie skryptów, wysłanie formularza i traktowania zawartości jako pochodzącej z tej samej domeny, za pomocą poniższych atrybutów:
<iframe sandbox="allow-forms allow-scripts allow-same-origin" src="redirectUri"> <!-- dokument strony uwierzytelniającej zawarty zostanie tutaj --> </iframe>
Deklaracje CSS, których należy użyć przy wyświetlaniu ramki na urządzeniu desktop:
.modal { display: none; /* domyślnie ukryty */ position: fixed; /* w tym samym miejscu */ z-index: 1; /* na wierchu */ left: 0; top: 0; width: 100%; /* Pełna szerokość */ height: 100%; /* Pełna wysokość */ background-color: rgb(0,0,0); /* kolor awaryjny */ background-color: rgba(0,0,0,0.4); /* czarny nieprzezroczysty */ } .modal-content { background-color: #fefefe; margin: auto; /* wyśrodkowanie */ border: 1px solid #888; height: 520px; /* maks. wysokość zawartości, włącznie z nagłówkiem */ width: 600px; /* maks. szerokość zawartości */ } iframe { border-style: hidden; height: 100%; width: 600px; /* maks. wysokość zawartości, włącznie z nagłówkiem */ margin: auto; }
Aby zawartość ramki iframe była responsywna należy do elementu <head> w dokumencie HTML dodać:
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
Deklaracje CSS przedstawione wcześniej w tym rozdziale powinny zostać nadpisane dla mniejszych ekranów:
@media (max-width: 599px) { .modal-content { width: 100%; margin: 0; /* wyśrodkowanie w pionie */ position: absolute; top: 50%; -ms-transform: translateY(-50%); transform: translateY(-50%); } iframe { width: 100%; /* wyświetlenie w pełnej dostępnej szerokości */ } }
Ramka może komunikować się z oknem głównym przez wartości zawarte w message.data:
Wartość DISPLAY_FRAME
może wystąpić 2 razy w przypadku 3DS challenge po którym następuje wyświetlenie formularza do podania kodu CVV.
W przypadku AUTHENTICATION_SUCCESSFUL
należy zaczekać na wynik uwierzytelnienia przed wyświetleniem jakichkolwiek informacji
na temat statusu
płatności. Aby odebrać wynik uwierzytelnienia, poczekaj na powiadomienie lub
pobierz
szczegóły zamówienia.
Istnieje kilka sposobów na szczegółowe obsłużenie powyższych przypadków. Możesz tylko zamknąć ramkę iframe, ale nadal wyświetlać informacje w oknie modalnym. Możesz również zamknąć okno modalne i iframe, a następnie załadować ponownie stronę aby wyświetlić dodatkowe informacje. Możesz także przygotować "preloader", który wyświetlany będzie w trakcie oczekiwania na wynik uwierzytelnienia.
Przykład jak odbierać i obsługiwać wiadomości z iframe:
window.addEventListener('message', handleMessage, false); function handleMessage(msg) { if (msg.origin === 'https://secure.payu.com') { switch (msg.data) { case ('DISPLAY_FRAME'): // pokazanie iframe jeżeli była ukryta break; case ('AUTHENTICATION_SUCCESSFUL'): // zamknięcie iframe, wykonanie innego konkretnego polecenia break; case ('AUTHENTICATION_CANCELED'): // zamknięcie iframe, wykonanie innego konkretnego polecenia break; } }