3DS 2

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 "EMVCo 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.

Płatności cykliczne i transakcje zainicjowane przez merchanta

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.

Transakcje niskokwotowe i o niskim ryzyku.

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.

Odmowa autoryzacji bez silnego uwierzytelnienia (tzw."soft decline")

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 przypadków "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).

Strona internetowa

Aby zwiększyć prawdopodobieństwo bezproblemowego uwierzytelnienia 3DS 2, zalecane jest przekazanie PayU dodatkowych informacji (tylko w przypadku integracji REST API).

Aplikacja mobilna

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").

Poniżej znajduje się lista kart symulujących podstawowe scenariusze testowe. Dla wszystkich z nich wystarczy podać dowolną przyszłą datę ważności (miesiąc/rok) i dowolne 3 cyfry jako CVV.

O nowe pola danych, związane z 3DS 2, zostało rozszerzone wyłącznie REST API.

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:

• transakcje z polem payMethods.payMethod.value ustawionym na jedną z płatności kartowych: c, ap, jp, ma, vc,
• transakcje z polem payMethods.payMethod.type ustawionym na CARD_TOKEN,
• transakcje z obiektem payMethods.card,
• transakcje bez obiektu 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.

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.

Tryb przeglądarkowy (Browser flow)

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

Tryb SDK

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

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:

Ponowienie autoryzacji

Należy zastosować następującą logikę:

1. Sprawdzenie powodu odrzucenia płatności kartą za pomocą pobrania danych transakcji.
2. Jeśli parametr 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.

Użycie strony PayU

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.

Tryb SDK (aplikacja mobilna obsługujące natywnie 3DS 2)

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.

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:

1. Przeprowadzi uwierzytelnienie korzystając z jednego z możliwych odstąpień SCA.
2. Jeżeli wydawca karty tego zażądał, będzie kontynuować z użyciem metody 3DS (device fingerprinting). Proces ten uwzględnia wysłanie formularza HTML z ukrytej ramki iframe, co może zająć do 10 sekund.
3. Wyświetli ekran "wyzwania" w ramce iframe, w celu pełnego uwierzytelnienia użytkownika.

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:

• &cvv=false - wyłącza formularz CVV (w przypadku gdy CVV jest wymagane, twoja strona musi być gotów je obsłużyć).
• &lang=[dwuliterowy kod językowy ISO] - wyłącza wykrywanie języka na stronie uwierzytelniającej i ustawia konkretny język (jeżeli jest wspierany).
• &header=false - strona uwierzytelniająca jest wyświetlana bez nagłówka.

Jeżeli w obiekcie buyer w OrderCreateRequest dostarczyłeś parametr language, PayU automatycznie doda go do URL.

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>
            

Wyśrodkowanie ramki

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

iframe na urządzeniach mobilnych

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 */
                }
            }
            

Odbieranie wiadomości z iframe

iframe może komunikować się z oknem głównym przez wartości zawarte we właściwości message.data:

• DISPLAY_FRAME - pokazuje ukrytą ramkę iframe.
• AUTHENTICATION_SUCCESSFUL - "wyzwanie" zakończyło sie sukcesem, zamknięcie iframe.
• AUTHENTICATION_CANCELED - "wyzwanie" zostało przerwane a płatność odrzucona, zamknięcie iframe.
• AUTHENTICATION_NOT_REQUIRED - uwierzytelnienie nie było potrzebne, zamknięcie iframe.

W przypadkach AUTHENTICAION_SUCCESSFUL i AUTHENTICATION_NOT_REQUIRED powinieneś 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 transakcji.

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_NOT_REQUIRED'):
                        // zamknięcie iframe, wykonanie innego konkretnego polecenia
                        break;
                    case ('AUTHENTICATION_SUCCESSFUL'):
                        // zamknięcie iframe, wykonanie innego konkretnego polecenia
                        break;
                    case ('AUTHENTICATION_CANCELED'):
                        // zamknięcie iframe, wykonanie innego konkretnego polecenia
                        break;
                }
            }