Przejdź do głównej zawartości

Rozszerzenia 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 załączone przez PayU.

Pola wymagane w standardzie 3DS 2​

Notatka

Jedynie interfejs REST API został wzbogacony o nowe parametry związane z 3DS 2.

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

Poniższa tabela zawiera parametry wymagane przez standard 3DS 2. Jest to minimum informacji, które są oczekiwane przy próbie uwierzytelnienia tym protokołem. Jeżeli pola nie zostaną przez Ciebie wypełnione, PayU prześle je z domyślnymi wartościami.

Dodatkowe komentarze do konkretnych pól
ParametrKomentarz
buyer.phone
Powinno się korzystać 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>state</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 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, zostanie stworzony domyślny obiekt (browser.requestIp zostanie zmapowane na podstawie customerIp).
threeDsAuthentication.recurring
W przypadku płatności cyklicznych (tj. transakcji oznaczonych za pomocą pola recurring o wartości FIRST lub STANDARD) sugerowane jest wysłanie tych danych w celu odpowiedniego oznaczenia typu uwierzytelnienia.
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".

Szczegółowe informacje na temat parametrów znajdziesz w sekcji Create an Order w naszej referencji API.

Przykład zamówienia​

Notatka

W tej sekcji znajduje się przykładowe zamówienie z minimalnymi danymi, które są wymagane przez PayU. Zamówienie zawiera 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"
        }
    }
}'

Odpowiedź do zamówienia z 3DS 2​

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​

Istniejąca odpowiedź ze statusem WARNING_CONTINUE_3DS została rozszerzona o pola threeDsProtocolVersion (obecnie zawsze 3DS2) i iframeAllowed. Wartości te wskazują na to, że parametr redirectUri może zostać wyświetlony w ramce iframe. Jeśli interesuje cię wykorzystanie ramki iframe zamiast pełnego przekierowania, zobacz sekcję Strona uwierzytelniania.

Przykładowa wzbogacona odpowiedź dla trybu przeglądarkowego
{
    "status": {
        "statusCode": "WARNING_CONTINUE_3DS",
        "severity": "WARNING"
    },
    "redirectUri": "{redirectUri}",
    "iframeAllowed": true,
    "threeDsProtocolVersion": "3DS2",
    "orderId": "QK52JR2VCR201023GUEST000P01"
}

Tryb sdk​

Parametr redirectUri nie będzie miał 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 wzbogacona odpowiedź dla trybu sdk
{
    "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"
}

Szczegóły 3DS w danych transakcji​

Możesz pobrać dane transakcji jeżeli zamówienie zostało odrzucone lub zakończone pomyślnie. Szczegóły parametrów zwracanych dzięki temu serwisowi znajdziesz w sekcji Retrieve a Transaction w naszej referencji API. Ta sekcja skupia się na wyjaśnieniu szczegółów odpowiedzi 3DS, na którą składają się poniższe pola:

  • cardEciCode
  • card3DsStatus
  • card3DsFrictionlessIndicator
  • card3DsStatusDescription

ECI​

ECI (Electronic Commerce Indicator) wskazuje poziom uwierzytelnienia transakcji. W praktyce, informuje o stronie odpowiedzialnej 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:

Notatka

  • full authentication nie wskazuje czy transakcja była uwierzytelnionia wraz z wyzwaniem (czy 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.

Kody ECI przy pobieraniu danych transakcyjnych
Poziom uwierzytelnieniaVisaMastercard
Pełne uwierzytelnienie. Odpowiedzialność po stronie wystawcy karty.
5
2
Próba Uwierzytelnienia częściowo udana. Wystawca karty nie uczestniczy w weryfikacji lub karta nie kwalifikuje się do uwierzytelnienia, lub serwer kontrolny wystawcy (ACS) nie jest aktualnie dostępny. Odpowiedzialność po stronie wystawcy karty.
6
1
Brak uwierzytelnienia. Odpowiedzialność po stronie Merchanta.
7
0
Brak uwierzytelnienia, dane z 3DS zostały wysłane do systemu karty płatniczej.
4
Pełne uwierzytelnienie, transakcja cykliczna
7
Notatka

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

Status 3DS​

Statusy 3DS przy pobieraniu danych transakcyjnych
StatusOpis
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").
I
Status informacyjny (wydawca karty zaakceptował wyjątek od silnego uwierzytelnienia).
Notatka

Nie jest to pełna lista statusów 3DS 2, obejmuje ona jedynie wartości, które można otrzymać w danych transakcyjnych.

Wskaźnik frictionless​

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, PayU przesyła 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 uwierzytelnienia dwuskładnikowego (2FA - Two-Factor Athentication), 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.

Possible values of frictionless indicator:

  • YES
  • NO
  • UNKNOWN

Opisy statusów 3DS​

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.

Opisy statusów 3DS
PozycjaŹródłoKomentarz
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).
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 bound. Więcej informacji na temat "wyzwania" znajdziesz w sekcji Wskaźnik 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 status ma określoną wartość.

Przykłady​

Poniżej znajdziesz 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"

Na tej stronie