Аутентификация 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 и, как следствие, способствовать повышению проходимости и улучшению пользовательского опыта. К базовому минимуму таких параметров можно отнести платёжный адрес пользователя (в параметрах объекта billing) и HTTP-заголовок User-Agent, полученный со стороны браузера (в параметре browser). Информация об этих и других параметрах представлена далее.

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

В платёжной платформе информирование мерчанта о необходимости аутентификации 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 и должен соответствовать описанному в статье Организация взаимодействия. Набор параметров, обязательных для этого платежа, должен соответствовать набору, описанному в статье про соответствующий тип платежа, включая разрешение экрана пользователя (параметр screen_res), его адрес электронной почты и номер его телефона (параметры email и phone соответственно) для оплат, и дополняться, в случае использования расширенной схемы, объектом acs_return_url с адресами веб-сервиса для перенаправления к нему пользователя и для получения уведомления от эмитента.

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

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

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

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

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

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

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

Данные для перенаправления пользователя передаются в объекте 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"
  // Данные о результате аутентификации
}