3DS 2

Nowy standard uwierzytelniania.

1 Wprowadzenie

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.

1.1 Czym jest 3DS 2

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.

1.2 PSD 2/SCA

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

Przeprowadzenie SCA jest wymagane od dostawców usług płatniczych w konkretnych przypadkach. Prawidłowa procedura silnego uwierzytelnienia wymaga potwierdzenia tożsamości klienta na dwa z trzech dostępnych sposobów:
  • wiedzą klienta (np. podanie hasła),
  • cechą klienta (np. odcisk palca),
  • własnością klienta (np. smartfon).

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.

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

Za niskokwotowe uznawane są transakcje do 30 EUR lub do równowartości tej kwoty w lokalnej walucie. Transakcje te są wyłączone z obowiązku SCA, z wyjątkiem dwóch przypadków:
  • w ciągu 24 godzin przeprowadzono transakcje bez silnego uwierzytelnienia, na łączną kwotę powyżej 100 EUR,
  • w ciągu 24 godzin wykonano 5 transakcji bez silnego uwierzytelnienia.
Po stronie wydawcy karty leży śledzenie liczby transakcji i potencjalnej potrzeby autoryzacji.

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

2 Wpływ na istniejące integracje

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.

2.1 Strona płatności PayU

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

2.2 Tokenizacja

Strona internetowa

Jeśli wykorzystujesz tokenizację kart (poprzez własny formularz lub widget PayU) na stronie internetowej, możesz:
  • nic nie zmieniać (użytkownicy będą przekierowywani na stronę uwierzytelniającą, tak jak dla 3DS 1),
  • skorzystać ze strony uwierzytelniającej PayU, wyświetlanej w ramce iframe.

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

2.3 Testowanie

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.

Numer Zachowanie
4245757666349685 Challenge wymagany
5150030090350186 3DS Method wymagana
4012001037141120 3DS Method i Challenge wymagane
5100052384536834 zwraca parametry Challenge jeżeli obiekt sdk został wysłany w OrderCreateRequest

3 Rozszerzenia API

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

3.1 Parametry dla 3DS 2

Aby móc wspierać transakcje z 3DS 2, dodaliśmy pola w obiekcie threeDsAuthentication w OrderCreateRequest. Opisy tych pól znajdują się w tabelach w tym rozdziale.

OrderCreateRequest - obiekt threeDsAuthentication

Przedstawione rozszerzenia API są w trakcie opracowywania. Nie należy uznawać poniższych informacji za ostateczne, gdyż mogą ulec niewielkim zmianom wraz z rozwojem usługi.
Parametr Opis Wymagalność
challengeRequested Preferencje merchanta w stosunku do sposobu uwierzytelnienia. Może zostać zastąpiony przez PayU. Możliwe wartości:
  • YES,
  • NO,
  • MANDATE.
Nie
browser Dane przeglądarki wymagane dla trybu przeglądarkowego 3DS 2. W przypadku braku podanych informacji zostaną one zebrane przez PayU.

Zaleca się załączanie tych informacji, ponieważ dzięki nim, w niektórych przypadkach obciążania zapisanych kart (z użyciem tokenu wielorazowego), możliwe jest ominięcie przekierowania na stronę uwierzytelniającą PayU.

Parametry tego obiektu opisane są w tabeli browser.
Nie, ale zalecane
sdk Wymagane jeżeli aplikacja mobilna merchanta wspiera 3DS 2. Zawartość musi być generowana przez certyfikowane 3DS 2 SDK

Ta informacja nie jest wymagana, ale zaleca się jej zamieszczanie w przypadku obciążania zapisanych kart (z użyciem tokenu wielorazowego).

Parametry tego obiektu opisane są w tabeli sdk.
Tak (jeżeli używane jest 3DS 2 SDK)
merchantRiskIndicator Zbiór pól pomocnych w ustaleniu ryzyka, związanego z samą transakcją (metoda dostawy, rodzaj sprzedanego produktu, itp.)

Parametry tego obiektu opisane są w tabeli merchantRiskIndicator.
Nie
recurring Dodatkowe informacje w przypadku płatności cyklicznej. Parametry tego obiektu opisane są w tabeli recurring. Nie
cardholder Zawiera dane konta właściciela karty posiadane przez merchanta, w tym szczegóły dotyczące konta użytkownika w systemie merchanta.

Parametry tego obiektu opisane są w tabeli cardholder.
Nie, ale zalecane

Obiekty zagnieżdżone

browser - opisy pól.

Parametr Opis Wymagalność
acceptHeaders Dokładna zawartość nagłówków HTTP accept, wysłanych z przeglądarki użytkownika. Tak
requestIP Adres IP przeglądarki zwracany przez nagłówki HTTP. Tak
screenWidth Całkowita szerokość ekranu użytkownika w pixelach. Pozyskane z właściwości HTML DOM - screen.width. Tak
javaEnabled Uzyskane z obiektu nawigatora HTML DOM. Tak
timezoneOffset Uzyskane z metody getTimezoneOffset() zastosowanej do obiektu Date. Tak
screenHeight Uzyskane z obiektu nawigatora HTML DOM. Tak
userAgent Dokładna zwartość nagłówka HTTP user-agent. Tak
colorDepth Uzyskane z przeglądarki uzytkownika, używającej właściwości HTML DOM - screen.colorDepth. Tak
language Uzyskane z przeglądarki użytkownika, używającej właściwości HTML DOM - navigator.language. Tak

sdk - opisy pól. Wszystkie pola w poniższej tabeli są generowane przez certyfikowane 3DS SDK.

Parametr Opis Wymagalność
sdkReferenceNumber Przykład: DS_LOA_SDK_ADBV_739485_94783 Tak
sdkMaxTimeout Wskazuje na maksymalny czas (w minutach) dla wszystkich wymian. Wartość tego pola będzie większa lub równa 05. Tak
sdkAppID Przykład: 9063b12c-fcde-43c7-b28e-8d0af5520e8a Tak
sdkEncData Dane zaszyfrowane przez 3DS SDK. Tak
sdkTransID Przykład: b60c9879-ac77-4918-a317-7b01c4317053/8Q==.. Tak
sdkEphemPubKey Publiczny komponent pary kluczy efemerycznych, wygenerowanych przez 3DS SDK w celu utworzenia kluczy sesyjnych pomiędzy SDK a wydawcą karty. Tak

merchantRiskIndicator - opisy pól.

Parametr Opis Wymagalność
orderType Możliwe wartości:
  • PURCHASE,
  • ACC_FUNDING,
  • QUASI-CASH,
  • LOAN.
Nie
shipIndicator Wskazuje na metodę dostawy, wybraną dla danej transakcji. Możliwe wartości:
  • BILLING_ADDRESS,
  • VERIFIED_ADDRESS,
  • OTHER_ADDRESS,
  • SHIP_TO_STORE,
  • DIGITAL_GOODS,
  • TICKETS,
  • NOT_SHIPPED.
Nie
preOrdered Wskazuje na to, czy przeprowadzana transakcja dotyczy produktu, który będzie dostępny w przyszłości (przedsprzedaż).

Typ danych: boolean.
Nie
preOrderDate Data zamówienia w przedsprzedaży. Format: "2019-03-27T10:57:59.000Z". Nie
deliveryTimeFrame Możliwe wartości:
  • ELECTRONIC,
  • SAME_DAY,
  • OVERNIGHT,
  • TWO_OR_MORE_DAYS.
Nie
reordered Informuje czy ten sam zakup został przeprowadzony ponownie.

Typ danych: boolean.
Nie
merchantFunds Wskazuje na częściowe opłacenie transakcji ze środków własnych merchanta (np. karta podarunkowa). Suma kwot zawartych tutaj i w polu totalAmount określa rzeczywistą kwotę transakcji w systemie merchanta.

Obiekt zawiera dwa pola: amount (w centach) i currency (kod ISO).
Nie

recurring - opisy pól.

Parametr Opis Wymagalność
frequencyDays Liczba dni między płatnościami. Nie
expiryDate Data, po której płatności nie będą już wykonywane. Format: "2019-03-27T10:57:59.000Z". Nie

cardholder - opisy pól.

Parametr Opis Wymagalność
name Imię i nazwisko właściciela karty. Nie
accountInformation Parametry tego obiektu są opisane w tabeli accountInformation. Nie
billingAddress Parametry tego obiektu są opisane w tabeli billingAddress. Nie

accountInformation - opisy pól.

Parametr Opis Wymagalność
createDate Data stworzenia konta właściciela karty w formacie "2019-03-27T10:57:59+00:00". Nie
suspiciousActivity Określa czy merchant spotkał się z podejrzanym/nieuczciwym zachowaniem związanym z tym kontem.

Typ danych: boolean.
Nie
deliveryAddressFirstUsedDate Data pierwszego użycia adresu dostawy wykorzystanego przy danej transakcji w formacie "2019-03-27T10:57:59+00:00". Nie
deliveryAddressUsageIndicator Wskazuje kiedy po raz pierwszy użyto danego adresu. Możliwe wartości:
  • THIS_TRANSACTION,
  • LESS_THAN_30_DAYS,
  • 30_TO_60_DAYS,
  • MORE_THAN_60_DAYS.
Nie
pastOrdersYear Zamówienia utworzone dla tego konta w systemie merchanta, w ciągu ostatnich 12 miesięcy. Nie
pastOrdersDay Zamówienia utworzone dla tego konta w systemie merchanta, w ciągu ostatnich 24 godzin. Nie
purchasesLastSixMonths Zamówienia, w systemie merchanta, dla tego konta zakończone sukcesem w ciągu ostatnich 6 miesięcy. Nie
changeDate Data ostatniej zmiany szczegółów konta w formacie "2019-03-27T10:57:59+00:00" Nie
changeIndicator Wskazuje kiedy ostatnio zmieniono szczegóły konta. Możliwe wartości:
  • THIS_TRANSACTION,
  • LESS_THAN_30_DAYS,
  • 30_TO_60_DAYS,
  • MORE_THAN_60_DAYS.
Nie
passwordChanged Data ostatniej zmiany hasła tego konta. Nie
passwordChangeIndicator Wskazuje czy i kiedy ostanio zmieniono hasło na koncie. Możliwe wartości:
  • THIS_TRANSACTION,
  • LESS_THAN_30_DAYS,
  • 30_TO_60_DAYS,
  • MORE_THAN_60_DAYS.
No
nameToRecipientMatch Wskazuje czy imię właściciela karty odpowiada imieniu beneficjenta.

Typ danych: boolean.
Nie
addCardAttemptsDay Wskazuje próby dodania karty do konta użytkownika w systemie merchanta, w ciągu ostatnich 24 godzin. Nie
authMethod Metody uwierzytelnienia tożsamości właściciela karty. Możliwe wartości:
  • GUEST,
  • LOGIN,
  • FEDERATED_ID,
  • THIRD_PARTY,
  • ISSUER,
  • FIDO.
Nie
authDateTime Data i czas przeprowadzenia uwierzytelnienia w formacie "2019-03-27T10:57:59+00:00". Nie
cardAddedDate Data zapisania danych karty u merchanta w formacie "2019-03-27T10:57:59+00:00". nie
cardAddedIndicator Wskazuje czy i kiedy dane karty zostały zapisane u merchanta. Możliwe wartości:
  • THIS_TRANSACTION,
  • LESS_THAN_30_DAYS,
  • 30_TO_60_DAYS,
  • MORE_THAN_60_DAYS.
Nie

billingAddress - opisy pól.

Parameters Description Required
street Pełna nazwa ulicy, włączając numer mieszkania. Nie
postalCode Kod pocztowy. Nie
city Nazwa miasta. Nie
state Nazwa stanu/województwa, jeżeli dotyczy. Nie
country Dwuliterowy kod językowy ISO, np. "CZ", "PL" lub "US". Nie

3.2 Parametry dla 3DS 2 - OrderCreateResponse

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 zostanie poszerzona o pole 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ź:

            {
               "orderId": "FMHJ6HZF3T190518GUEST000P01",
               "status": {
                  "statusCode": "WARNING_CONTINUE_3DS",
                  "severity": "WARNING"
               },
               "redirectUri": "https://secure.payu.com/front/threeds?token=averylongjsonwebtokenwillbehere",
               "iframeAllowed": true
            }
            

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

            {
               "challengeParameters": {
                  "threeDsServerTransactionId": "12345678-1234-5678-abcd-eFABCDEF0123",
                  "acsTransID": "d7c1ee99-9478-44a6-b1f2-391e29c6b340",
                  "acsReferenceNumber": "3DS_LOA_ACS_201_13579",
                  "acsSignedContent": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cDovL3d3dy4zZHMuY29tL25vdGlmaWNhdGlvbi11cmwiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhhODgwZGMwLWQyZDItN9"
               }
            }
            

4 Obsługa przypadków "soft decline"

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.

5 Strona uwierzytelniająca

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

5.1 Przegląd procesu

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.

5.2 Parametry query string

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.

5.3 Obsługa ramki iframe

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