Аутентификация 3‑D Secure

Обзор

Аутентификация пользователя с использованием протокола 3‑D Secure (Three-Domain Secure) предназначена для безопасного проведения интернет-оплат с использованием платёжных карт. Она может выполняться с применением различных методов проверки подлинности пользователя: например, через указание пользователем одноразового проверочного кода (One Time PIN, OTP), с помощью проверки отпечатка пальца пользователя на его мобильном устройстве или без каких-либо действий со стороны пользователя, на основе информации о платеже и пользователе. В разных случаях могут поддерживаться различные методы проверки.

В аутентификации 3‑D Secure могут задействоваться три домена:

• Домен эквайера. В рамках работы с платёжной платформой ecommpay к нему относятся веб-сервис мерчанта, платёжная платформа и связанный с ней 3DS-сервер.
• Домен совместимости. К нему относятся серверы каталогов (Directory Servers, DS) международных платёжных систем.
• Домен эмитента. К нему относятся серверы управления доступом (Access Control Servers, ACS) эмитента (и страницы аутентификации).

Между этими доменами осуществляется обмен сообщениями, необходимыми для аутентификации пользователя. К таким сообщениям относятся запрос на проверку возможности проведения аутентификации (Verifying Enrolment Request, VEReq) и ответ на него (Verifying Enrolment Response, VERes), а также запрос на аутентификацию пользователя (Challenge Request, CReq) и ответ с информацией о результате аутентификации (Challenge Response, CRes).

Следует учитывать, что информация о возможности аутентификации пользователя и о версии протокола, по которой необходимо выполнять аутентификацию, хранится на сервере управления доступом, и эту информацию можно получить только после отправки запроса на проведение платежа. Также со стороны веб-сервиса и платёжной платформы невозможно отслеживать действия пользователей на странице аутентификации — доступно только получение информации о результате аутентификации.

Варианты аутентификации

Аутентификация 3‑D Secure может выполняться в следующих вариантах:

• Аутентификация без участия пользователя (frictionless flow). Выбор эмитентом этого варианта, как правило, способствует повышению проходимости и улучшению пользовательского опыта.
• Аутентификация с подтверждением пользователем своей личности (challenge flow). Подтверждение личности может выполняться, например, с использованием одноразового кода или биометрических данных, если такая возможность поддерживается эмитентом.

Со стороны мерчанта выбрать требуемый вариант аутентификации нельзя, поддерживается только указание предпочтений по такому выбору, но итоговое решение принимается на стороне эмитента. Также, помимо указания предпочтений в запросах на проведение платежа можно передавать ряд других необязательных параметров, применение которых может повысить вероятность выбора варианта аутентификации frictionless flow.

Схемы работы

В платёжной платформе ecommpay аутентификация 3‑D Secure может выполняться при проведении карточных одностадийных и двухстадийных оплат, а также при проверках действительности платёжных карт. При этом может использоваться одна из двух схем выполнения аутентификации: базовая (proxy) и расширенная (native).

Перейти от использования базовой схемы к использованию расширенной можно в любое время, без дополнительных согласований со специалистами ecommpay. Для этого достаточно передать в запросе на проведение платежа параметры, обязательные для расширенной схемы. Эти параметры перечислены далее, в разделе Формат запросов на проведение платежей.

Пользовательские сценарии

В зависимости от используемой схемы, варианта аутентификации, выбранного эмитентом, и других факторов процесс аутентификации может выглядеть по-разному. Так, при аутентификации пользователю могут отображаться страница ожидания на стороне веб-сервиса или платформы и ACS-страница на стороне эмитента.

На примере расширенной схемы пользовательский сценарий может выглядеть следующим образом.

Рис.: Страница указания платёжных данных

Рис.: Страница ожидания

Рис.: Страница ACS

Рис.: Страница ожидания

Рис.: Итоговая страница

Базовая схема

В платёжной платформе информирование мерчанта о необходимости аутентификации 3‑D Secure осуществляется через оповещения, при приёме которых, как обычно при работе с платформой, необходимо отправлять ответы.

В базовой схеме оповещения о необходимости аутентификации содержат объект acs, и в качестве реагирования на такие оповещения необходимо перенаправить пользователя на страницу эмитента, принять сведения о результате аутентификации и отправить эти сведения в запросе на продолжение платежа. Время ожидания в платформе такого запроса составляет, как правило, 30 минут и измеряется с момента выявления необходимости аутентификации и до получения запроса от веб-сервиса. Если время ожидания истекло и запрос не принят — платёж автоматически отклоняется.

После поступления в платёжную платформу информации о результате аутентификации проведение платежа продолжается. В случае, если подключено каскадное проведение платежей, может понадобиться принять одно или несколько дополнительных оповещений о необходимости аутентификации 3‑D Secure. Если полученное оповещение содержит параметр cascading_with_redirect со значением true, необходимо:

• Отобразить пользователю страницу с сообщением об ошибке и получить его согласие на повторную аутентификацию.
• Отреагировать на оповещение необходимым способом.

Информацию о каскадном проведении платежей можно получить в соответствующей статье или у специалистов технической поддержки .

Информация о форматах запросов и оповещений приведена далее; общая информация о работе с API — в разделе Организация взаимодействия.

Расширенная схема

В платёжной платформе информирование о необходимости аутентификации 3‑D Secure осуществляется через оповещения, при приёме которых необходимо отправлять ответы. Такое информирование не осуществляется только в тех случаях, когда со стороны эмитента принято решение об аутентификации пользователя без предоставления дополнительных сведений. В этих случаях со стороны веб-сервиса не требуется действий, отличных от стандартных при проведении платежа, а информация о результате аутентификации передаётся в итоговом оповещении.

При использовании расширенной схемы оповещение о необходимости аутентификации содержит объект iframe (в объекте threeds2). В качестве реагирования на это оповещение необходимо:

1. Отобразить пользователю элемента iframe с использованием данных из оповещения.
2. Принять от сервера управления доступом (ACS) эмитента уведомление о приёме данных и отправить в платёжную платформу запрос на инициирование аутентификации.
3. В случае выбора эмитентом варианта аутентификации frictionless flow — принять информацию о результате аутентификации, а в случае выбора варианта аутентификации challenge flow выполнить следущие действия:
   • принять от платёжной платформы оповещение с объектом redirect (в объекте threeds2) и отправить ответ о приёме этого оповещения;
   • перенаправить пользователя на страницу аутентификации в течение 30 секунд после приёма оповещения;
   • принять от эмитента данных о результате аутентификации;
   • отправить в платформу запрос на продолжение проведение платежа с учётом результата аутентификации (3ds_result) в течение 30 минут после выявления необходимости аутентификации.

После поступления в платёжную платформу информации о результате аутентификации проведение платежа продолжается. В случае, если подключено каскадное проведение платежей, может понадобиться принять одно или несколько дополнительных оповещений с объектом redirect. Если такое оповещение содержит параметр cascading_with_redirect со значением true, необходимо:

• Отобразить пользователю страницу с сообщением об ошибке и получить его согласие на повторную аутентификацию.
• Отреагировать на оповещение необходимым способом.

Информацию о каскадном проведении платежей можно получить в соответствующей статье или у специалистов технической поддержки support@ecommpay.com.

Информация о форматах оповещений и запросов, используемых в этой схеме, приведена в разделе Форматы промежуточных сообщений для расширенной схемы; общая информация о работе с Gate API — в разделе Организация взаимодействия.

Общая информация

Формат запроса на проведение платежа не влияет на возможность выполнения аутентификации 3‑D Secure и должен соответствовать описанному в статье Организация взаимодействия. Набор параметров, обязательных для этого платежа, должен соответствовать набору, описанному в статье про соответствующий тип платежа, и дополняться, в случае использования расширенной схемы, объектом acs_return_url с адресами веб-сервиса для перенаправления к нему пользователя и для получения уведомления от эмитента.

Вместе с тем, в числе необязательных параметров рекомендуется передавать информацию о платеже (такую как предпочтительный вариант аутентификации и выбранный способ доставки) и о пользователе (такую как платёжный адрес и контактные данные пользователя) — это может повысить вероятность выбора варианта аутентификации frictionless flow, то есть варианта аутентификации пользователя без каких-либо действий с его стороны. Со стороны веб-сервиса мерчанта можно передавать как все, так и только некоторые из этих параметров. К базовому минимуму можно отнести адрес электронной почты пользователя (параметр email), его платёжный адрес (параметры объекта billing) и номер телефона (параметр phone), а также разрешение экрана пользователя (параметр screen_res) и значение HTTP-заголовка User-Agent, полученного со стороны его браузера (параметр browser).

Обязательные параметры

При использовании расширенной схемы в запросах на проведение платежей необходимо передавать объект acs_return_url со следующими параметрами.

Начиная с 12 августа 2024 года при проведении оплат с использованием карт платёжной системы Visa в запросах на проведение платежей необходимо передавать объект customer со следующими параметрами.

В запросах на проверку платёжных инструментов (тип платежа account verification) передавать эти параметры не требуется.

Рекомендуемые параметры

При использовании базовой и расширенной схем в запросах на проведения платежей рекомендуется передавать следующую информацию о платеже и пользователе.

Формат оповещения о необходимости аутентификации

При использовании базовой схемы аутентификации от платёжной платформы к веб-сервису передаётся оповещение с данными для перенаправления пользователя. Оповещение передаётся в стандартном формате, описание которого представлено в разделе Оповещения.

Данные для перенаправления пользователя передаются в объекте acs. К таким данным относятся: сообщение CReq (в параметре pa_req) для направления запроса на прохождение аутентификации 3‑D Secure эмитенту, адрес страницы аутентификации (acs_url) и данные мерчанта в платёжной системе — Merchant Data (md).

"acs":{  
  "pa_req":"inLgICAiYWNzVHIDAtMDAwMDAwMDAwNHv5hu", // Сообщение CReq
  "acs_url":"https://example.com/ACS", // Адрес страницы для перенаправления
  "md":"eyJwdXJjaGFzZV9vcGVyYXRpb25faWRfaWJ9" // Данные мерчанта в платёжной системе
}

Формат запроса на перенаправление

Для перенаправления пользователя на страницу аутентификации или страницу провайдера необходимо направить запрос на адрес, полученный в оповещении о необходимости аутентификации. Это должен быть POST-запрос со следующими объектами и параметрами:

• action — адрес страницы, на которую необходимо перенаправить пользователя, полученный в параметре acs_url оповещения;
• PaReq — сообщение CReq, полученное в параметре pa_req оповещения;
• TermUrl — адрес для перенаправления пользователя к веб-сервису после аутентификации;
• MD — данные мерчанта в международной платёжной системе (Merchant Data), полученные в параметре md оповещения.

<form id="3dsform" action="https://example.com/ACS" method="post" enctype="application/
x-www-form-urlencoded">
    <input type="hidden" name="PaReq" value="inLgICAiYWNzVHIDAtMDAwMDAwMDAwNHv5hu" />
    <input type="hidden" name="TermUrl" value="http://example.com/termurl" />
    <input type="hidden" name="MD" value="eyJwdXJjaGFzZV9vcGVyYXRpb25faWRfaWJ9" />
</form>
<script type="text/javascript">
    setTimeout(function() {
        document.getElementById("3dsform").submit();
    }, 1000);
</script>

Для удобства можно воспользоваться готовым примером — Пример HTML-формы, — заменив параметры на актуальные для платежа.

Формат уведомления о результате аутентификации

Данные о результате аутентификации передаются к веб-сервису в параметре pares.

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFU9IiwibWRTdGF0dXMiOjEsIm1kRXJyb3JNc2ciOiJBdXRoZW50aWNhdGVkIiwiZW5yb2xsbWVuU3RhdHVzIjpudWxsLCJhdXRoZW50aWNhdGlvblN0YXR1cyI6IlkiLCJjYXZ2IjoiUVVOVFJVMVZLMkI5UFV4MWFXRXBhMlJpTjJVPSIsImVjaSI6IjA1In0=

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFk9IiwibWRTdGF0dXMiOjAsIm1kRXJyb3JNc2ciOiJOb3QgYXV0aGVudGljYXRlZCIsImVucm9sbG1lblN0YXR1cyI6bnVsbCwiYXV0aGVudGljYXRpb25TdGF0dXMiOiJOIiwiY2F2diI6IiIsImVjaSI6IiJ9

Формат запроса на продолжение платежа

Для продолжения проведения платежа с учётом результата аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/3ds_result. В этом запросе должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись к данным запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
• pares — сведения о результате аутентификации 3‑D Secure, полученные в уведомлении.

Таким образом, корректный запрос на продолжение проведения платежа с учётом результата аутентификации 3‑D Secure должен содержать идентификаторы проекта и платежа, подпись и данные о результате аутентификации.

{
   "general": {
   "project_id": 42,
   "payment_id": "456789",
   "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
   },
   "pares": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi
LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR
FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1
N0YXR1cyIgOiAiWSIKfQ"
  // Сведения о результате аутентификации
}

Формат оповещения с данными для объекта iframe

При расширенной схеме аутентификации через Gate от платёжной платформы к веб-сервису могут передаваться оповещения с данными для формирования объекта iframe. Для этих оповещений используется стандартный формат, описание которого представлено в разделе Оповещения.

Оповещения с данными для формирования объекта iframe не передаются, если со стороны эмитента без использования данных об устройстве пользователя принято одно из следующих решений:

• Выполнить проверку пользователя с перенаправлением на страницу аутентификации (вариант challenge flow). В этом случае со стороны веб-сервиса необходимо принять и обработать оповещение с данными для перенаправления (подробнее — ниже).
• Аутентифицировать пользователя (вариант frictionless flow). В этом случае со стороны веб-сервиса необходимо принять и обработать оповещение о результате проведения платежа.

Следующий пример содержит данные для формирования объекта iframe. Эти данные необходимо использовать следующим образом: адрес из параметра url — в атрибуте action, а данные из других параметров — в тегах input.

{ 
  "threeds2":{ 
    "iframe":{ 
      "url":"https://example.com",
      "params":{
        "3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ",
        "threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"
      }
    }
  }
}

<iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" style="width: 1px; height: 1px; 
display: none;" src="javascript:false;" xmlns="http://example.com/xhtml"> <!--.--> </iframe>
<form id="tdsMmethodForm" name="tdsMmethodForm" action="https://example.com" method="post" 
target="tdsMmethodTgtFrame" xmlns="http://example.com/xhtml">
    <input type="hidden" name="3DSMethodData" value="eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ"
    />
    <input type="hidden" name="threeDSMethodData" value="eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"
    />
</form>
<script type="text/javascript" xmlns="http://example.com/xhtml">
    document.getElementById("tdsMmethodForm").submit();
</script>

Формат оповещения о необходимости аутентификации

При использовании расширенной схемы аутентификации через Gate от платёжной платформы к веб-сервису могут передаваться оповещения с данными для перенаправления пользователя на страницу аутентификации (ACS URL) эмитента. Оповещения передаются в стандартном формате, описание которого представлено в разделе Оповещения. Оповещения с данными для перенаправления пользователя на страницу аутентификации не передаются в случаях, если на стороне эмитента выбран вариант аутентификации frictionless flow. Вместо такого оповещения со стороны веб-сервиса необходимо принять и обработать оповещение о результате проведения платежа.

Следующий пример содержит данные для перенаправления пользователя на страницу аутентификации. Эти данные необходимо использовать следующим образом: адрес из параметра url — в атрибуте action, а данные из других параметров — в тегах input.

{ 
  "threeds2":{ 
    "redirect":{ 
      "url":"https://example.com/ACS",
      "params":{
        "creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9",
        "threeDSSessionData":"240000549"
      }
    }
  }
}

<!DOCTYPE html SYSTEM "about:legacy-compat">
<html class="no-js" lang="en" xmlns="http://example.com/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta charset="utf-8" />
    <title>3D Secure Processing</title>
    <link href="https://example.com/mpi.css" rel="stylesheet" type="text/css" />
  </head>
  <body>
    <div id="main">
      <div id="content">
        <div id="order">
          <h2>3D Secure Processing</h2>
          <img src="https://example.com/preloader.gif" alt="Please wait.." /> <img src="https://
example.com/verifiedbyvisa.png" alt="Verified by VISA" />
          <div id="formdiv">
            <script type="text/javascript">
              function hideAndSubmitTimed(formid) { timer=setTimeout("hideAndSubmit('"+formid+"');",
100);} function hideAndSubmit(formid) { var formx=document.getElementById(formid); tif (formx!=null)
{ formx.style.visibility="hidden"; formx.submit(); } }
            </script>
            <div>
              <form id="webform0" name="red2ACSv2" method="POST" action="https://
example.com/ACS" accept_charset="UTF-8"> 
<input type="hidden" name="_charset_" value="UTF-8" /> 
<input type="hidden" name="creq" value="ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9" /> 
<input type="hidden" name="threeDSSessionData" value="240000476" /> 
<input type="submit" name="submitBtn" value="Please click here to continue" /> 
              </form>
            </div>
          </div>
          <script type="text/javascript">
           thideAndSubmitTimed('webform0');
          </script>
          <noscript>
            <div align="center"> <b>Javascript is turned off or not supported!</b> <br/> </div>
          </noscript>
        </div>
      </div>
    </div>
  </body>
</html>

Формат уведомления о приёме данных об устройстве пользователя

При расширенной схеме аутентификации от сервера управления доступом (ACS) эмитента на URL веб-сервиса, указанный в запросе на проведение платежа (в параметре 3ds_notification_url), передаётся уведомление о приёме данных об устройстве пользователя. Это уведомление передаётся в формате эмитента.

threeDSServerTransID=3abd37b3-afa6-53cf-8000-000000006455

Формат запроса на инициирование аутентификации

При расширенной схеме аутентификации для инициирования аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/3ds_check_iframe. В запросе к этой конечной точке должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись к данным запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
• threeds_completion_indicator — указатель получения уведомления о приёме данных в течение десяти секунд после открытия объекта iframe. Необходимо передать значение true при получении уведомления и значение false при его отсутствии в заданный период.

Таким образом, корректный запрос на инициирование аутентификации 3‑D Secure должен содержать идентификаторы проекта и платежа и подпись.

{ 
  "general":{ 
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "threeds_completion_indicator":true
}

Формат уведомления о результате аутентификации

При использовании расширенной схемы аутентификации через Gate данные о результате аутентификации передаются к веб-сервису в формате эмитента. Эти данные передаются в параметре cres уведомления.

cres=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ&threeDSSessionData=240000554

cres=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogIjhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAiTiIKfQ==&threeDSSessionData=240000622

Формат запроса на продолжение платежа

При базовой и расширенной схемах аутентификации через Gate для продолжения проведения платежа с учётом результата аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/3ds_result. В этом запросе должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись к данным запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
• cres — данные о результате аутентификации 3‑D Secure, полученные в уведомлении от сервера управления доступом.

Таким образом, корректный запрос на продолжение проведения платежа с учётом результата аутентификации 3‑D Secure должен содержать идентификаторы проекта и платежа, подпись и данные о результате аутентификации.

{
   "general": {
   "project_id": 42,
   "payment_id": "456789",
   "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
   },
   "cres": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi
LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR
FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1
N0YXR1cyIgOiAiWSIKfQ"
  // Данные о результате аутентификации
}