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

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

Dane kart testowych znajdują na stronie "sandbox".

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

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:

• cardEciCode
• card3DsStatus
• card3DsFrictionlessIndicator
• card3DsStatusDescription

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:

• "full authentication" nie wskazuje czy transakcja była uwierzytelnionia wraz z "wyzwaniem" (właściciel karty musiał wykonać dodatkową akcję, zgodną z wymogiem "Strong Customer Authentication") lub bez udziału właściciela karty (frictionless).
• "attempted authentication" oznacza, że PayU próbowało uwierzytelnić transakcję, ale wystawca karty nie był w stanie przeprowadzić uwierzytelnienia (w większości przypadków spowodowane to jest brakiem przypisania karty do usługi 3DS).
• W przypadku kart Mastercard, może zaistnieć sytuacja, w której nieuwierzytelniona transakcja podlega przetwarzaniu 3DS określonego jako "data-only" (oficjalnie: Digital Transaction Insights). Przesłanie "data-only" wzbogaca podpowiedzi, które Mastercard przekazuje wystawcy karty. Nie powoduje to jednak, że transakcja będzie traktowana jako uwierzytelniona.

Wartości ECI zależą od systemu karty płatniczej:

Nie jest to pełna lista dostępnych kodów ECI, obejmuje ona jedynie wartości, które można otrzymać w danych transakcyjnych.

• Y - uwierzytelnienie zakończone pomyślnie
• N - brak uwierzytelnienia (zwykle z powodu nieudanego "wyzwania")
• U - nie można było uwierzytelnić (problem techniczny, karta nie przypisana do 3DS lub uwierzytelnienie "data-only")
• A - próba przetworzona (brak uwierzytelnienia, ale został przedstawiony dowód na próbę uwierzytelnienia)
• R - odrzucone ( silniejsza wersja statusu "N", wystawca karty odrzuca ją bez zainicjowania "wyzwania")

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:

• YES
• NO
• UNKNOWN

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

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"

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.

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

• użyj danych karty: numer 5100052384536818 z datą ważności 02/2032 i dowolną wartością CVV,
• dane karty powinny zostać wprowadzone na stronie płatniczej PayU, zamienione na token za pomocą Secure Form (tokenizacja typu SINGLE) lub przesyłane w czystej postaci (without tokenization),
• wyślij OrderCreateRequest z polem 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:

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).
• &sendCreq=[true/false; domyślnie: true] - strona nie wysyła komunikatu CReq (challenge request) wyświetlającego stronę z challenge. Parametr ma zastosowanie w przypadku dwukrotnego wczytania strony (raz w ukrytej ramce, drugi raz w widocznej ramce lub w pełnym przekierowaniu). W takim przypadku pierwsze wczytanie powinno odbyć się z zastosowaniem wartości false, ponieważ komunikat CReq może zostać wysłany tylko raz.

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

Ramka 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 ramki

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

• DISPLAY_FRAME - należy pokazać ukrytą ramkę.
• AUTHENTICATION_SUCCESSFUL - uwierzytelnienie zostało zakończone, należy zamknąć ramkę. Uwaga: termin SUCCESSFUL ma sens techniczny (brak błędów), nie przesądza tego, że udało się poprawnie uwierzytelnić posiadacza karty.
• AUTHENTICATION_CANCELED - należy zamknąć ramkę, wystąpił błąd techniczny.

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