3D Secure (3DS) to protokół uwierzytelniania, który dodaje dodatkową warstwę zabezpieczeń do płatności online

Gdy klient inicjuje płatność, 3DS wymaga od niego ukończenia dodatkowego etapu uwierzytelniania u wydawcy karty. Zazwyczaj wiąże się to z przekierowaniem klienta na stronę internetową jego banku, gdzie wprowadza on hasło lub kod wysłany na telefon w celu weryfikacji płatności. Ta dodatkowa warstwa uwierzytelniania pomaga chronić firmę przed nieuczciwymi transakcjami i zapewnia większe bezpieczeństwo płatności.

3D Secure 2 (3DS2) to zaktualizowany i wysoce bezpieczny protokół uwierzytelniania, który został zaprojektowany specjalnie w celu spełnienia wymagań Silnego Uwierzytelniania Klienta (SCA) dla płatności online.

Korzyści

Jeśli chodzi o nieuczciwe obciążenia zwrotne (na przykład roszczenie o obciążenie zwrotne z powodu zgubionej lub skradzionej karty), odpowiedzialność zazwyczaj przenosi się ze sprzedawcy na wydawcę karty po pomyślnym uwierzytelnieniu płatności za pomocą 3DS.

Oznacza to, że jeśli płatność została dokonana przy użyciu 3D Secure, a posiadacz karty zakwestionuje płatność jako nieuczciwą, nie będziesz ponosić odpowiedzialności za jakiekolwiek straty Zamiast tego wydawca karty będzie odpowiedzialny za zwrot pieniędzy posiadaczowi karty i wszelkie powiązane opłaty.

3DS 2 Flows

3DS2 zapewnia lepsze wrażenia użytkownika poprzez płynne osadzenie procesu uwierzytelniania w przepływie płatności, ulepszając oryginalny protokół 3DS.

Podczas procesu płatności 3DS2 umożliwia sprzedawcy i dostawcy płatności wysyłanie elementów danych, w tym adresu wysyłki klienta, identyfikatora urządzenia i historii płatności, do banku posiadacza karty. Informacje te są wykorzystywane do oceny poziomu ryzyka transakcji, a wszystko to odbywa się w tle, w ramach internetowego lub mobilnego przepływu płatności.

Na podstawie tych danych bank klienta albo natychmiast uwierzytelni płatność, co jest znane jako frictionless flow (transakcja płatnicza bez żądania dodatkowego uwierzytelnienia), albo poprosi o dodatkowe informacje przed uwierzytelnieniem płatności, co jest znane jako challenge flow(transakcja płatnicza z żądaniem dodatkowego uwierzytelnienia).

Płatność za pomocą 3DS

Protokół uwierzytelniania 3-D Secure jest zgodny z modelem trójdomenowym, w którym domena Acquirer Domain i domena Issuer Domain są połączone domeną Interoperability Domain. Głównym celem tego modelu jest uwierzytelnienie posiadacza karty podczas transakcji e-commerce lub zapewnienie weryfikacji tożsamości i potwierdzenia konta.

Protokół ten dotyczy klientów, którzy dokonują zakupów online u sprzedawców posiadających sklepy internetowe zgodne z wytycznymi 3D-Secure. Więcej informacji można znaleźć na stronie: https://www.emvco.com/emv-technologies/3d-secure/.

Przepływ rozpoczyna się od standardowego przepływu autoryzacji lub zakupu, w którym początkowa odpowiedź na żądanie POST {id}card/purchase wskazuje, że wymagane jest uwierzytelnianie 3D-Secure To wskazanie jest dostarczane w postaci paymentStatus: „Partial”, po którym następuje nowy złożony element o nazwie „actionResponse„.

Uwierzytelnianie 3D-Secure może odbywać się automatycznie i płynnie (Frictionless Flow) lub wymagać wyraźnego uwierzytelnienia przez klienta na platformie emitenta (Challenge Flow).

Jak to działa

Aby wykonać płatność z autoryzacją 3DS, najpierw utwórz zamówienie zgodnie z instrukcjami zawartymi w Przewodniku integracji API (Full-Code).

Następnie możesz przystąpić do dokonania płatności.

Należy pamiętać, że do wiadomości z żądaniem należy dodać DeviceInfo:

Element danych	Typ	Stan	Opis
deviceInfo	DeviceInfo	Obowiązkowe	Obiekt definiujący informacje o urządzeniu klienta.
browserAcceptHeader	Ciąg	Opcjonalnie	Nagłówek akceptacji przeglądarki
browserJavaEnabled	Ciąg	Opcjonalnie	Przeglądarka z włączoną obsługą Java
browserJavascriptEnabled	Ciąg	Opcjonalnie	Włączona obsługa Javascript w przeglądarce
browserLanguage	Ciąg	Opcjonalnie	Język przeglądarki
browserColorDepth	Ciąg	Opcjonalnie	Głębia kolorów przeglądarki
browserScreenHeight	Ciąg	Opcjonalnie	Wysokość ekranu przeglądarki
browserScreenWidth	Ciąg	Opcjonalnie	Szerokość ekranu przeglądarki
browserTZ	Ciąg	Opcjonalnie	Strefa czasowa przeglądarki
browserUserAgent	Ciąg	Opcjonalnie	Agent użytkownika przeglądarki
systemFamily	Ciąg	Opcjonalnie	Rodzina systemów
systemVersion	Ciąg	Opcjonalnie	Wersja systemu
systemArchitecture	Ciąg	Opcjonalnie	Architektura systemu
deviceManufacturer	Ciąg	Opcjonalnie	Producent urządzenia
deviceModel	Ciąg	Opcjonalnie	Model urządzenia
deviceID	Ciąg	Opcjonalnie	Unikalna identyfikacja urządzenia
applicationName	Ciąg	Opcjonalnie	Nazwa aplikacji
applicationVersion	Ciąg	Opcjonalnie	Wersja aplikacji
geoLocalization	Ciąg	Opcjonalnie	Geolokalizacja
ipAddress	Ciąg	Opcjonalnie	Adres IP

Tutaj możesz sprawdzić przykładowe żądanie:

{
    "info": {
        "deviceInfo": {
            "browserAcceptHeader": "application/json, text/plain, */*",
            "browserJavaEnabled": "false",
            "browserLanguage": "en",
            "browserColorDepth": "24",
            "browserScreenHeight": "1080",
            "browserScreenWidth": "1920",
            "browserTZ": "-60",
            "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
            "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
            "systemFamily": "Windows",
            "systemVersion": "Windows",
            "deviceID": "498bfd4c3a3645b38667a7037b616c18",
            "applicationName": "Chrome",
            "applicationVersion": "106"
        },
        "customerInfo": [
            {
                "key": "customerName",
                "value": "Diogo M"
            },
            {
                "key": "customerEmail",
                "value": "{{CustomerEmail}}"
            }
        ]
    },
    "cardInfo": {
        "PAN": "{{MC3DSCardNum}}",
        "secureCode": "{{MC3DSCardCVV}}",
        "validationDate": "{{MC3DSCardExpiry}}",
        "cardholderName": "TKN {{trxDatetime}}",
        "createToken": true
    }
}

Otrzymasz odpowiedź zawierającą w wiadomości status płatności. Informuje on, czy transakcja została zaakceptowana, odrzucona, nadal oczekuje na ostateczny wynik lub wymaga dodatkowych działań.

• Sukces: Zakup został pomyślnie przetworzony, a klient został obciążony.
• Odrzucono: Zakup został odrzucony.
• W toku: Ostateczny wynik zakupu nie jest jeszcze znany. Konieczne będzie zapytanie o status tej transakcji, dopóki nie osiągnie ona stanu końcowego lub użytkownik nie zdecyduje się jej anulować.
• Częściowy: Zakup został częściowo zaakceptowany, ale wymaga wykonania dodatkowych czynności (np. Uwierzytelnianie 3D Secure). Element actionResponse zawiera instrukcje dotyczące dalszego postępowania.

Jeśli otrzymany status płatności to „Partial”, oznacza to, że przed ponownym wysłaniem wniosku o płatność kartą należy wysłać dodatkowe żądanie uwierzytelnienia 3DS (Challenge Flow).

Odpowiedź będzie również zawierać element actionResponse z informacjami o tym, jak postępować, jak pokazano w poniższym przykładzie.

Zapisz identyfikator actionResponse.id, aby użyć go do ponownego przesłania żądania płatności po zakończeniu uwierzytelniania 3DS.

Oto przykład pełnej odpowiedzi wraz z odpowiedzią na akcję:

{
    "transactionID": "2Cm5pP09QcP1pUq7WpPs",
    "execution": {
        "startTime": "2023-06-20T13:10:55.328Z",
        "endTime": "2023-06-20T13:10:57.484Z"
    },
    "paymentStatus": "Partial",
    "actionResponse": {
        "id": "b114d9a9-4d6b-4ff8-ab95-be4e11cc8235",
        "type": "THREEDS_CHALLENGE",
        "data": {
            "url": "https://api-aws.sibs.ro/sandbox/sibs/public/acsSample",
            "params": [
                {
                    "name": "creq",
                    "data": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImIxMTRkOWE5LTRkNmItNGZmOC1hYjk1LWJlNGUxMWNjODIzNSIsImFjc1RyYW5zSUQiMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAxIn0="
                }
            ]
        }
    },
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Partial",
        "statusDescription": "Partial"
    }
}

Następnie musisz wykonać trzy dodatkowe działania:

Działanie 1: Przekierowanie posiadacza karty do ACS w celu uwierzytelnienia 3DS

Działanie 2: Ponowne przesłanie transakcji do ostatecznej autoryzacji

Działanie 3: Wykonanie polecenia Uzyskaj Status

Działanie 1: Przekierowanie posiadacza karty do ACS w celu uwierzytelnienia 3DS

Przeglądarka klienta musi zostać przekierowana przez POST do adresu URL serwera kontroli dostępu 3DS (ACS) wskazanego przez actionResponse.data.url przy użyciu actionResponse.data.params jako parametrów żądania.

Po zakończeniu uwierzytelniania przeglądarka posiadacza karty jest przekierowywana z powrotem do źródła.

Przykład przekierowania do ACS w Javascript

POST "https://api-aws.sibs.ro/sandbox/sibs/public/acsSample"

creq: eyJ0aHJlZURTU(...)

Działanie 2: Ponowne przesłanie transakcji do ostatecznej autoryzacji

W tym żądaniu zakupu należy dodać obiekt actionProcessed, jak pokazano poniżej:

Element danych	Typ	Stan	Opis
actionProcessed	ActionProcessed	Opcjonalnie
id	Ciąg	Obowiązkowe
typ	Ciąg	Obowiązkowe	Możliwe wartości to „THREEDS_METHOD”, „THREEDS_CHALLENGE”, „DCC”, „INSTALLMENTS”
wykonany	logiczna	Obowiązkowe

Przykład żądania:

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/card/purchase

Nagłówki żądań:

Authorization: ‘Digest <transactionSignature>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json

{
    "info": {
        "deviceInfo": {
            "browserAcceptHeader": "application/json, text/plain, */*",
            "browserJavaEnabled": "false",
            "browserLanguage": "en",
            "browserColorDepth": "24",
            "browserScreenHeight": "1080",
            "browserScreenWidth": "1920",
            "browserTZ": "-60",
            "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
            "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
            "systemFamily": "Windows",
            "systemVersion": "Windows",
            "deviceID": "498bfd4c3a3645b38667a7037b616c18",
            "applicationName": "Chrome",
            "applicationVersion": "106"
        },
        "customerInfo": [
            {
                "key": "customerName",
                "value": "Diogo M"
            },
            {
                "key": "customerEmail",
                "value": "{{CustomerEmail}}"
            }
        ]
    },
    "cardInfo": {
        "PAN": "{{MC3DSCardNum}}",
        "secureCode": "{{MC3DSCardCVV}}",
        "validationDate": "{{MC3DSCardExpiry}}",
        "cardholderName": "TKN {{trxDatetime}}",
        "createToken": true
    },
    "actionProcessed": {
    "id": "{{actionId}}",
    "type": "THREEDS_CHALLENGE",
    "executed": true
    }
}

Oczekiwana odpowiedź:

Jak widzieliśmy wcześniej, paymentStatus w odpowiedzi informuje o tym, czy sama transakcja została odrzucona, przetworzona pomyślnie, czy też wymaga jeszcze innego działania.

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

Jeśli status płatności to „Częściowa„, wykonaj czynności opisane w punkcie 1.

Oto przykład udanej płatności:

{
    "transactionID": "2Cm5pP09QcP1pUq7WpPs",
    "execution": {
        "startTime": "2023-06-20T13:11:14.236Z",
        "endTime": "2023-06-20T13:11:17.535Z"
    },
    "paymentStatus": "Success",
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success",
        "statusDescription": "Success"
    },
    "actionResponse": {
        "data": {
            "params": []
        }
    }
}

Działanie 3: Wykonanie polecenia Uzyskaj Status

Po pełnym przetworzeniu płatności można sprawdzić status transakcji, wysyłając żądanie GET.

Upewnij się, że nagłówek HTTP Authorization jest ustawiony na ten sam token Bearer, który został użyty w początkowym zleceniu płatności.

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Nagłówki żądań:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

Oto przykład odpowiedzi:

Kod wyniku	statusMsg	Opis	Działanie
HTTP-200	Sukces	Reakcja na sukces	nie dotyczy
HTTP-400	Zła prośba	Ładunek JSON nie jest zgodny z definicją API (FULL CODE) lub brakuje niektórych obowiązkowych nagłówków HTTP.	Sprawdź w API Market poprawną składnię.
HTTP-401	Nieautoryzowany	Podczas autoryzacji token okaziciela jest nieprawidłowy/wygasł lub nie jest powiązany z używanym terminalem.	Sprawdź w SIBS Backoffice w sekcji Credentials, czy token jest ważny i w razie potrzeby utwórz nowy.
HTTP-403	Zakazane	ClientID ustawiony w nagłówku HTTP X-IBM-Client-Id jest nieprawidłowy lub nie posiada ważnej subskrypcji API	Sprawdź w SIBS Backoffice pod SPG APP 2.0, czy ClientID jest poprawny. Jeśli problem nadal występuje, skontaktuj się z pomocą techniczną SIBS Gateway w celu zresetowania ClientID.
HTTP-405	Niedozwolona metoda	Użyta metoda HTTP nie pasuje do żadnej z dostępnych definicji API.	Sprawdź w API Market prawidłową metodę HTTP.
HTTP-429	Zbyt wiele żądań	Limit połączeń API został przekroczony.	Informacje na temat limitów stawek mających zastosowanie do API można znaleźć w API Market.
HTTP-500	Wewnętrzny błąd serwera	Wywołanie API nie powiodło się… i najprawdopodobniej po naszej stronie.	Należy ponowić operację, a jeśli problem nie ustąpi, skontaktować się z pomocą techniczną SIBS Gateway w celu uzyskania pomocy.
HTTP-503	Usługa niedostępna	Wywołanie API nie jest obecnie dostępne. Zwykle jesteśmy zawsze włączeni, ale podczas zaplanowanej konserwacji mogą wystąpić krótkie problemy z dostępnością.	Powinieneś poczekać i spróbować ponownie później.

Oto przykład odpowiedzi:

{
    "merchant": {
        "terminalId": "101774",
        "merchantTransactionId": "Order Id: r7cxvi0saj"
    },
    "transactionID": "2Cm5pP09QcP1pUq7WpPs",
    "amount": {
        "currency": "PLN",
        "value": "50.50"
    },
    "paymentType": "PURS",
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "execution": {
        "endTime": "2023-06-20T13:11:23.411Z",
        "startTime": "2023-06-20T13:11:23.327Z"
    },
    "returnStatus": {
        "statusCode": "000",
        "statusMsg": "Success",
        "statusDescription": "Success"
    }
}