5.2. Обзор 3DS
Процесс 3DS в ConnPay
Справочные материалы:
EMV® 3-D Secure Protocol and Core Functions Specification
Несмотря на различия в обмене сообщениями на низком уровне, по существу версия протокола 2.X отличается от 1.0 наличием опции автоматической оценки рисков эмитентом карты на основе дополнительных контекстных данных, отправляемых из браузера или мобильного приложения плательщика, тогда как версия 1.0 всегда требует от плательщика прохождения проверки (challenge). Соответственно (и согласно спецификации EMVCo), протокол версии 2.X включает в себя Frictionless flow (сбор контекстных данных и оценка рисков) и Challenge flow (прохождение проверки аутентификации). Стандартный процесс аутентификации 3DS 2.X в веб-браузере плательщика проиллюстрирован ниже.
Плательщики заполняют платежную форму, предоставленную Подключенной стороной или Платежным шлюзом, и отправляют данные.
Примечание
Для транзакций перевода платежная форма может выглядеть так, как описано ниже.
Контекстные данные собираются и отправляются Эмитенту в фоновом режиме внутри браузера (Frictionless flow).
Если Эмитент считает транзакцию рискованной, браузер плательщика перенаправляется на веб-страницу Эмитента для прохождения проверки аутентификации (Challenge flow).
Когда плательщик проходит проверки, выполняется авторизация платежа с сохранением деталей аутентификации 3DS на стороне эквайера.
Браузер плательщика перенаправляется на сайт Подключенной стороны на страницу с результатом.
В связи с тем, что обе версии протокола все еще используются, Подключенная сторона должна поддерживать их обе, а также специфические интеграции, когда эквайер берет на себя взаимодействие по 3D Secure. Для этих целей Платежный шлюз предоставляет универсальный подход на основе API-команд, которые позволяют Подключенной стороне обрабатывать все указанные случаи. Подключенной стороне следует начать со Схемы принятия решений 3DS для соответствующего варианта использования (Use-Case), которая, в свою очередь, ссылается на более детальную диаграмму, описывающую специфику обработки данных и редиректов браузера плательщика.
Сценарии реализации 3DS
Сценарий реализации |
Инструкции |
|---|---|
3DS не инициируется (non3D). |
Аутентификация 3DS не инициируется. Следуйте Схеме принятия решений 3DS соответствующего Use-Case и реализуйте Процесс Non3D. |
3DS инициируется и выполняется Подключенной стороной (для PSP и эквайеров). |
Аутентификация 3DS инициируется и выполняется Подключенной стороной, результаты передаются в Платежный шлюз в первоначальном запросе. Следуйте Схеме принятия решений 3DS соответствующего Use-Case и реализуйте Процесс Non3D (3DS выполняется до первоначального запроса к Платежному шлюзу). |
3DS инициируется Платежным шлюзом и выполняется на стороне Подключенной стороны. |
Аутентификация 3DS инициируется Платежным шлюзом. Для 3DS 1.0.2 аутентификация плательщика выполняется на стороне Подключенной стороны, результаты загружаются в Платежный шлюз. Для 3DS 2.x выполнение 3DS Method и Challenge происходит на стороне Подключенной стороны, результаты загружаются в Платежный шлюз. Дополнительные поля для 3DS Method могут быть переданы Подключенной стороной в первоначальном запросе для ускорения процесса в 3DS 2.x (tds_status=MethodUrlFrame будет пропущен, если 3DS Method не поддерживается ACS). Следуйте Схеме принятия решений 3DS соответствующего Use-Case и реализуйте все процессы 3DS (3DS Flows). |
3DS инициируется и выполняется Платежным шлюзом. |
Аутентификация 3DS инициируется Платежным шлюзом, все сценарии 3DS выполняются на стороне Платежного шлюза. Следуйте Схеме принятия решений 3DS соответствующего Use-Case, реализуйте Упрощенный процесс аутентификации (игнорируйте наличие параметра tds_status, используйте параметры html или redirect-to для перенаправления плательщика на Платежный шлюз) и Процесс Non3D (если карта плательщика не участвует в 3DS или обработка идет как Non3D). |
Схема принятия решений 3DS
Подключенная сторона должна реализовать все шаги, отмеченные зеленым и фиолетовым цветами. Ниже приведены описания шагов со ссылками на конкретные API-команды в соответствии с ID шага:
Процесс Non3D
Транзакция должна считаться non3D (без аутентификации 3DS), если соблюдены все условия:
Примечание
Обратите внимание, что статус транзакции «unknown» может возникать как для 3DS, так и для non3D транзакций. Подробности см. в разделе Statuses.
Процесс 3DS 2.x.0 Frictionless
Подключенная сторона должна реализовать все шаги, отмеченные зеленым цветом. Ниже приведены описания шагов со ссылками на конкретные API-команды в соответствии с ID шага:
Пример HTML-страницы 3DS Method
Приведенный ниже пример HTML-страницы 3DS Method выполняет инициацию 3DS Method через iframe и удерживает браузер плательщика до завершения 3DS Method на сервере Подключенной стороны. После завершения или по истечении тайм-аута Подключенная сторона должна выполнить следующие шаги согласно Схеме принятия решений 3DS и перенаправить браузер плательщика на соответствующий URL (либо Challenge Flow, либо страницу результата платежа). Стандартное значение тайм-аута — 30 сек.
HTML-страница 3DS Method состоит из следующих параметров:
Параметр |
Описание |
|---|---|
tds-method-url-frame-3ds-method-url |
URL ACS 3DS Method, полученный Подключенной стороной в ответе /api/v2/status/. |
tdsMethodUploadUrl |
URL Подключенной стороны, на который приходит результат после завершения процесса. |
threeDSMethodData |
Значение JSON, содержащее threeDSServerTransID и threeDSMethodNotificationURL. См. ниже, как сформировать threeDSMethodData. |
Формирование threeDSMethodData
Для того чтобы сформировать threeDSMethodData, Подключенная сторона должна использовать следующие параметры.
Параметр |
Описание |
|---|---|
threeDSServerTransID |
Универсальный уникальный идентификатор транзакции, присвоенный 3DS-сервером для идентификации отдельной транзакции.
Получается в ответе /api/v2/status/ как параметр tds-method-url-frame-3ds-server-trans-id.
|
threeDSMethodNotificationURL |
URL, на который придет уведомление о завершении 3DS Method от ACS. Подключенная сторона несет ответственность за предоставление корректного threeDSMethodNotificationURL. Обычно, когда Подключенная сторона получает любой запрос на этот URL, она должна вернуть 3DS Method Done HTML Page (см. пример ниже). |
Пример формирования threeDSMethodData
Сформируйте JSON threeDSMethodData.
{"threeDSServerTransID":"3d671629-a410-4a5d-9288-b38ceadd41f2","threeDSMethodNotificationURL":"https://connectingparty.com/3ds-method-complete/"}
Примените кодирование base64 url к результирующему JSON.
eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNkNjcxNjI5LWE0MTAtNGE1ZC05Mjg4LWIzOGNlYWRkNDFmMiIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL21lcmNoYW50LmNvbS8zZHMtbWV0aG9kLWNvbXBsZXRlLyJ9
Генерация Fingerprint
3DS Method может опционально использоваться эмитентами для сбора отпечатков браузера (fingerprints) с помощью JavaScript. Это делается путем загрузки URL в скрытом iframe перед аутентификацией. Этот iframe выполнит JavaScript-код для снятия отпечатка, после чего отправит POST-запрос на заранее определенный URL запрашивающей стороны. Результат снятия отпечатка 3DS Method привязывается к аутентификации через threeDSServerTransID.
function gatherBrowserData() {
var colorDepth = screen.colorDepth; // 24
var javaEnabled = navigator.javaEnabled(); // true
var browserLanguage = navigator.language; // en_US
var screenHeight = screen.height; // 1080
var screenWidth = screen.width; // 1920
var userAgent = navigator.userAgent; // Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36
var browserTimezoneZoneOffset = new Date().getTimezoneOffset(); // 0
}
Пример создания HTML-страницы 3DS Method:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>ACS v2 3DS Method ...</title>
<style>
.progress{
position: absolute;
height: 10px;
width: 100%;
}
.progress .color{
position: absolute;
background-color: #444;
width: 100%;
height: 10px;
animation: progres 11s linear;
}
@keyframes progres{
0%{
width: 0%;
background-color: #ddd;
}
25%{
width: 50%;
background-color: #ccc;
}
50%{
width: 75%;
background-color: #bbb;
}
75%{
width: 85%;
background-color: #aaa;
}
100%{
width: 100%;
background-color: #777;
}
};
</style>
<script>
var fallbackTimeout = null;
function processForm() {
document.title = "ACS v2 AReq ...";
document.getElementById( "browserJavaEnabled" ).value = navigator.javaEnabled();
document.getElementById( "browserJavascriptEnabled" ).value = true;
document.getElementById( "browserLanguage" ).value = navigator.language;
document.getElementById( "browserColorDepth" ).value = screen.colorDepth;
document.getElementById( "browserScreenHeight" ).value = screen.height;
document.getElementById( "browserScreenWidth" ).value = screen.width;
document.getElementById( "browserTZ" ).value = new Date().getTimezoneOffset();
document.autoForm.submit();
}
function onPostMessage(event) {
if(!event.data.hasOwnProperty('methodNotification')) {
return;
}
if(fallbackTimeout != null) {
clearTimeout(fallbackTimeout);
fallbackTimeout = null;
}
document.getElementById( "threeDSCompInd" ).value = 'Y';
processForm();
}
function onPageLoaded() {
fallbackTimeout = setTimeout(processForm, 10 * 1000);
document.methodForm.submit();
window.addEventListener('message', onPostMessage);
}
</script>
</head>
<body onload="onPageLoaded()">
<div class="progress">
<div class="color"></div>
</div>
<iframe style="width:0; height:0; border:0;" name="methodFrame"></iframe>
<form name="methodForm" target="methodFrame" action="[=tds-method-url-frame-3ds-method-url]" method="POST">
<input type="hidden" name="threeDSMethodData" value="[=threeDSMethodData]">
</form>
<form name="autoForm" action="[=tdsMethodUploadUrl]" method="post">
<input type="hidden" name="threeDSServerTransID" value="[=threeDSServerTransID]"/>
<input type="hidden" name="threeDSCompInd" id="threeDSCompInd" value="N"/>
<input type="hidden" name="browserJavaEnabled" id="browserJavaEnabled" value="" />
<input type="hidden" name="browserJavascriptEnabled" id="browserJavascriptEnabled" value="" />
<input type="hidden" name="browserLanguage" id="browserLanguage" value="" />
<input type="hidden" name="browserColorDepth" id="browserColorDepth" value="" />
<input type="hidden" name="browserScreenHeight" id="browserScreenHeight" value="" />
<input type="hidden" name="browserScreenWidth" id="browserScreenWidth" value="" />
<input type="hidden" name="browserTZ" id="browserTZ" value="" />
<noscript>
<input type="submit" name="submit" value="Upload 3DS Method Result"/>
</noscript>
</form>
</body>
</html>
Обработка уведомления 3DS Method
Когда 3DS Method завершен, Подключенная сторона получает HTTP POST запрос на threeDSMethodNotificationURL с данными threeDSMethodData, которые содержат threeDSServerTransID (в JSON с кодировкой base64).
Получите threeDSMethodData.
threeDSMethodData=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNkNjcxNjI5LWE0MTAtNGE1ZC05Mjg4LWIzOGNlYWRkNDFmMiJ9Cg
Примените декодирование base64 url для получения JSON, содержащего threeDSServerTransID.
{"threeDSServerTransID":"3d671629-a410-4a5d-9288-b38ceadd41f2"}
Пример HTML-страницы 3DS Method Done
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>ACS v2 3DS Method Notification Handler...</title>
<script>
window.parent.postMessage({ methodNotification: "COMPLETE" }, "*");
</script>
</head>
<body>
<p>This should not be displayed</p>
</body>
</html>
Процесс 3DS 2.x.0 Challenge
Пример HTML-страницы CReq
HTML-страница CReq перенаправляет браузер плательщика на URL ACS-сервера, указанный в параметре tds-creq-form-acs-url. Результирующее значение CRes будет возвращено от ACS на notificationURL, предоставленный Подключенной стороной в запросе /api/3ds/v1/upload-method-url-result/ во время процесса 3DS 2.x.0 Frictionless.
Поле |
Описание |
Обязательность |
|---|---|---|
creq |
Данные ACS 3DS CReq, полученные Подключенной стороной в ответе /api/v2/status/. То же, что и tds-creq-form-creq. |
Обязательно |
threeDSSessionData |
значение, которое будет отправлено обратно в CRes на notificationURL в конце процесса. Максимальная длина: 1024 байта, формат: буквенно-цифровой, кодировка Base64url без дополнения (padding). |
Опционально |
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Redirecting ...</title>
<script type="text/javascript" language="javascript">
function makeSubmit() {
document.returnform.submit();
}
</script>
</head>
<body onLoad="makeSubmit()">
<form name="returnform" action="https://acs.bank-domain.com/mdpayacs/creq" method="POST">
<input type="hidden" name="creq" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImM1NDA5N2VhLTc0ZTctNDE2My05MTQ4LTNjMTY1NTg3NGIwMCIsImFjc1RyYW5zSUQiOiIxMjU1NTkyMi1lZmYzLTRjOTQtOTk4Mi0yMDM3NjJhMzdmMjkiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDIiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=">
<input type="hidden" name="threeDSSessionData" value="NjY4MDU3NQ">
<noscript>
<input type="submit" name="submit" value="Press this button to continue"/>
</noscript>
</form>
</body>
</html>
Процесс аутентификации 3DS 1.0.2
Пример HTML-страницы PaReq
HTML-страница PaReq перенаправляет браузер плательщика на URL ACS-сервера, указанный в параметре tds-pareq-form-acs-url.
HTML-страница PaReq состоит из следующих параметров:
Поле |
Описание |
Обязательность |
|---|---|---|
tds-pareq-form-acs-url |
URL ACS 3DS PaReq, полученный Подключенной стороной в ответе /api/v2/status/. |
Обязательно |
MD |
Данные Подключенной стороны, которые возвращаются на вашу страницу завершения. |
Опционально |
PaReq |
Данные ACS 3DS PaReq, полученные Подключенной стороной в ответе /api/v2/status/. То же, что и tds-pareq-form-pareq. |
Обязательно |
TermURL |
URL страницы завершения, на которую плательщик перенаправляется обратно с переданными данными PaRes. |
Обязательно |
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Loading acs..</title>
<script type="text/javascript" language="javascript">
function makeSubmit() {
document.returnform.submit();
}
</script>
</head>
<body onLoad="makeSubmit()">
<form name="returnform" action="$tds-pareq-form-acs-url" method="POST">
<input type="hidden" name="MD" value="some_merchant_data"/>
<input type="hidden" name="PaReq" value="$tds-pareq-form-pareq"/>
<input type="hidden" name="TermUrl" value="https://termination.page"/>
<noscript>
<input type="submit" name="submit" value="Submit"/>
</noscript>
</form>
</body>
</html>
Упрощенный процесс аутентификации
Альтернативная аутентификация держателя карты
Платежный шлюз поддерживает альтернативные методы аутентификации держателя карты, если карта не участвует в 3DS (отрицательный ответ 3DS enrollment). Одним из таких методов является проверка случайной суммы. В этом методе Платежный шлюз инициирует дополнительную транзакцию преавторизации для удержания случайной небольшой суммы на счету держателя карты и отправляет специальную форму для ввода плательщиком удержанной суммы. Если сумма указана верно, Платежный шлюз продолжает обработку первоначальной транзакции. Удержание небольшой суммы отменяется автоматически.
Общая диаграмма для транзакций через форму
Общая диаграмма для прямых интеграций
