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

Обзор

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

В аутентификации 3‑D Secure используются три домена:

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

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

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

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

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

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

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

Схемы выполнения аутентификации

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

Подробная информация о схемах выполнения аутентификации 3‑D Secure представлена в этой статье.

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

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

В базовой схеме аутентификации оповещения о необходимости аутентификации содержат объект acs (если провайдер не участвует в аутентификации) или redirectData (если провайдер участвует в аутентификации). Реагирование на такие оповещения сводится к следующему:

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

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

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

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

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

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

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

Оповещение о необходимости аутентификации в этом случае содержит объект iframe (в объекте threeds2). Реагирование на это оповещение в целом сводится к следующему:

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

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

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

При использовании базовой схемы аутентификации от платёжной платформы к веб-сервису передаётся оповещение с данными для перенаправления пользователя. Оповещение передаётся в стандартном формате, описание которого представлено в разделе Оповещения. Данные для перенаправления пользователя передаются в одном из объектов такого оповещения: acs (если провайдер не участвует в аутентификации) или redirectData (если провайдер участвует в аутентификации).

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

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

В объекте redirectData оповещения передаются следующие данные: тело запроса (body), метод отправки запроса (method) и адрес провайдера (url).

"redirectData":{
  "method":"GET", // Метод отправки запроса
  "body":[  ], // Тело запроса (может быть пустым)
  "encrypted": [  ],
  "url":"https://example.com/..."
}

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

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

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

  Метод отправки запроса — POST.

• Если данные получены в объекте redirectData:
  • action — адрес провайдера, полученный в параметре url оповещения;
  • method — метод отправки запроса, полученный в параметре method оповещения;
  • body — тело запроса, если оно получено в оповещении.

<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=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFU9IiwibWRTdGF0dXMiOjEsIm1kRXJyb3JNc2ciOiJBdXRoZW5
            0aWNhdGVkIiwiZW5yb2xsbWVuU3RhdHVzIjpudWxsLCJhdXRoZW50aWNhdGlvblN0YXR1cyI6IlkiLCJjYXZ2I
            joiUVVOVFJVMVZLMkI5UFV4MWFXRXBhMlJpTjJVPSIsImVjaSI6IjA1In0=

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFk9IiwibWRTdGF0dXMiOjAsIm1kRXJyb3JNc2ciOiJOb3QgYXV
            0aGVudGljYXRlZCIsImVucm9sbG1lblN0YXR1cyI6bnVsbCwiYXV0aGVudGljYXRpb25TdGF0dXMiOiJOIiwiY
            2F2diI6IiIsImVjaSI6IiJ9

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

Для продолжения проведения платежа с учётом результата аутентификации необходимо отправить в платёжную платформу 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>

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

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

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

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

Если в запросе на проведение платежа передан параметр 3ds_notification_url, при расширенной схеме аутентификации через Gate для инициирования аутентификации необходимо отправить в платёжную платформу 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=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHl
             wZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFu
             c0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgO
             iAiWSIKfQ&threeDSSessionData=240000554

cres=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDA
             wLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCi
             AgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogI
             jhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAi
             TiIKfQ==&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"
  // Данные о результате аутентификации
}