Аутентификация по протоколу 3‑D Secure 1

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

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

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

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

Между этими доменами осуществляется обмен сообщениями, необходимыми для аутентификации пользователя. В первой версии протокола 3‑D Secure — 3‑D Secure 1 — к таким сообщениям относятся запрос на проверку возможности проведения аутентификации (Verifying Enrolment Request, VEReq) и ответ на него (Verifying Enrolment Response, VERes), а также запрос на аутентификацию пользователя (Payer Authentication Request, PAReq) и ответ с данными о результате аутентификации (Payer Authentication Response, PARes).

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

Со стороны веб-сервиса для аутентификации 3‑D Secure 1 необходимо:

• принять оповещение (или несколько оповещений в рамках одного платежа) о необходимости аутентификации 3‑D Secure 1;
• отреагировать на это оповещение;
• перенаправить пользователя на страницу аутентификации с отправкой запроса на аутентификацию (PAReq);
• если это необходимо, принять данные о результате аутентификации (PARes) и отправить эти данные в платежную платформу.

Более подробные сведения о работе с аутентификацией 3‑D Secure 1 представлены далее.

Схема работы

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

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

• Если оповещение содержит объект acs, необходимо: перенаправить пользователя на страницу аутентификации (ACS URL) эмитента с использованием данных из оповещения, принять данные о результате аутентификации от эмитента и отправить эти данные в запросе на продолжение платежа. Время ожидания такого запроса составляет, как правило, 30 минут и измеряется с момента выявления необходимости аутентификации и до получения запроса от веб-сервиса. Если время ожидания истекло и запрос не принят — платеж автоматически отклоняется.
• Если оповещение содержит объект redirect_data, необходимо перенаправить пользователя на страницу провайдера. Дальнейших действий со стороны веб-сервиса в этом случае не требуется. Информацию о ситуациях, при которых может понадобиться этот способ реагирования, можно получить у курирующего менеджера JetPay.

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

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

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

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

Оповещение с данными для перенаправления

Для передачи данных для перенаправления используются оповещения стандартного формата, описание которого представлено в разделе Оповещения (callbacks) в Gate. Данные для перенаправления пользователя передаются в одном из объектов такого оповещения: acs или redirect_data.

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

"acs":{  
  "pa_req":"eJxVUtluwyAQ/BUrH2DA...n8/4htjT7Em", // Сообщение PAReq 
  "acs_url":"https://example.com/ACS",
                              // Адрес страницы аутентификации
  "md":"eyJfto7jg456ZCI6IiJ9" // Данные мерчанта в платежной системе
}

Если параметр body не содержит данных, он представлен в оповещении как пустой массив, в противном случае он присутствует в оповещении как JSON-объект с данными. Далее приведены примеры представления body в оповещении.

"redirect_data": {
              "body": [],    // Пустой массив 
              "method": "POST",
              "url": "https://example.com/redirect/absd1234",
}

"redirect_data": {
            "body": {       // Объект с данными
                 "reference": "2000016"                 
              },
              "method": "POST",
              "url": "https://example.com/redirect/absd1234",
}

Запрос на перенаправление

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

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

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

  Рис.: Пример HTML-формы с данными из объекта acs

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

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

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

Запрос на продолжение проведения платежа

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

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

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

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "pares": "eJzVWdfvq8iy/iujOY/WDBnbI+9ldZMMJpho4I1...Dfn76en3N+f/A1fJrSU="
}