.. meta::
   :description: Обзор 3-D Secure в API Payneteasy: процесс аутентификации держателя карты, версии 3DS 1.0 и 2.x, challenge ACS, бесшовный процесс и перенос ответственности.

.. _3ds_overview_reference:

Обзор 3DS
########################

.. role:: ex

.. role:: code



.. _3ds_flow_overview_reference:

Процесс 3DS в Payneteasy
----------------------------------------------------

Справочные материалы:

|EMV_link|

.. |EMV_link| raw:: html

   <a href="https://www.emvco.com/emv-technologies/3d-secure/" rel="nofollow noopener noreferrer">EMV® 3-D Secure Protocol and Core Functions Specification</a>

| 3-D Secure — это протокол, разработанный в качестве дополнительного уровня безопасности для онлайн-транзакций по кредитным и дебетовым картам.
| Протокол 3-D Secure имеет две основные версии.

| 1.0 — была представлена в 2001 году и до сих пор используется некоторыми эквайерами (сервисы на базе этого протокола были приняты различными платежными системами под разными названиями: Verified by Visa или Visa Secure у Visa, SecureCode у Mastercard, ProtectBy у Discover, J/Secure у JCB International, American Express SafeKey у American Express).
| 2.X — была представлена в 2016 году для усиления и замены версии 1.0; она направлена на соблюдение новых требований ЕС к аутентификации и устранение некоторых недостатков оригинального протокола.

Несмотря на различия в обмене сообщениями на низком уровне, по существу версия протокола 2.X отличается от 1.0 наличием опции автоматической оценки рисков эмитентом карты на основе дополнительных контекстных данных, отправляемых из браузера или мобильного приложения плательщика, тогда как версия 1.0 всегда требует от плательщика прохождения проверки (challenge). Соответственно (и согласно спецификации EMVCo), протокол версии 2.X включает в себя Frictionless flow (сбор контекстных данных и оценка рисков) и Challenge flow (прохождение проверки аутентификации). Стандартный процесс аутентификации 3DS 2.X в веб-браузере плательщика проиллюстрирован ниже.

1. Плательщики заполняют платежную форму, предоставленную Подключенной стороной или Платежным шлюзом, и отправляют данные.

.. image:: /_static/images/3ds_server_to_server_sale_flow/payment_form.png
  :alt: Платёжная Форма
  :align: center
  :width: 550

|

.. note:: Для транзакций перевода платежная форма может выглядеть так, как описано ниже.

.. image:: /_static/images/3ds_server_to_server_transfer_flow/transfer_flow.png
  :alt: Платёжная Форма
  :align: center
  :width: 550

|

2. Контекстные данные собираются и отправляются Эмитенту в фоновом режиме внутри браузера (Frictionless flow).

.. image:: /_static/images/3ds_server_to_server_sale_flow/wait_form.png
  :alt: Форма Ожидания
  :align: center
  :width: 550

|

3. Если Эмитент считает транзакцию рискованной, браузер плательщика перенаправляется на веб-страницу Эмитента для прохождения проверки аутентификации (Challenge flow).

.. image:: /_static/images/3ds_server_to_server_sale_flow/3ds.png
  :alt: 3DS
  :align: center
  :width: 450

|

4. Когда плательщик проходит проверки, выполняется авторизация платежа с сохранением деталей аутентификации 3DS на стороне эквайера.

.. image:: /_static/images/3ds_server_to_server_sale_flow/wait_form.png
  :alt: Форма Ожидания
  :align: center
  :width: 550

|

5. Браузер Плательщика перенаправляется на сайт Присоединяющейся Стороны на страницу с результатом.

.. image:: /_static/images/3ds_server_to_server_sale_flow/finish_form.png
  :alt: Финальная форма
  :align: center
  :width: 550

|

В связи с тем, что обе версии протокола все еще используются, Подключенная сторона должна поддерживать их обе, а также специфические интеграции, когда эквайер берет на себя взаимодействие по 3D Secure. Для этих целей Платежный шлюз предоставляет универсальный подход на основе API-команд, которые позволяют Подключенной стороне обрабатывать все указанные случаи. Подключенной стороне следует начать со Схемы принятия решений 3DS для соответствующего варианта использования (Use-Case), которая, в свою очередь, ссылается на более детальную диаграмму, описывающую специфику обработки данных и редиректов браузера плательщика.

.. _3ds_implementation_scenarios:

Сценарии реализации 3DS
------------------------------------------------------

.. list-table::
   :widths: 50, 50
   :header-rows: 1
   :class: longtable

   * - Сценарий реализации
     - Инструкции
   * - 3DS не инициируется (non3D).
     - Аутентификация 3DS не инициируется. Следуйте Схеме принятия решений 3DS соответствующего Use-Case и реализуйте Сценарий без 3DS.
   * - 3DS инициируется и выполняется Подключенной стороной (для PSP и эквайеров).
     - Аутентификация 3DS инициируется и выполняется Подключенной стороной, результаты передаются в Платежный шлюз в первоначальном запросе. Следуйте Схеме принятия решений 3DS соответствующего Use-Case и реализуйте Сценарий без 3DS (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 для перенаправления плательщика на Платежный шлюз) и Сценарий без 3DS (если карта плательщика не участвует в 3DS или обработка идет как Non3D).

.. _3ds_decision_making_scheme_overview:

Схема прохождения 3DS
-----------------------------------------

.. uml::
  :align: center

  @startuml
  <style>
  activityDiagram {
  BackgroundColor #Turquoise
    diamond {
      BackgroundColor #Turquoise
    }
  }
  document {
     BackgroundColor #fcfcfc
  }
  </style>
  title Схема прохождения 3DS
  start
  : (1) Send **/api/v2/status** request\nwith orderid=**paynet-order-id**\nProcess **/api/v2/status** response;
  while ((2) Check If **status** response field equals\nto finished status values\n**status** == approved\nOR **status** == declined\nOR **status** == error\nOR **status** == unknown\nOR **status** == filtered) is (NO);
  if ((3) **tds_status** field is present) then (YES)
  if ((4) **tds_status** == MethodUrlFrame?) then (YES)
  #Plum :(5) Create iframe\nto pass 3DS Method\n3DS 2.x Frictionless flow\nto be applied.\n\nSee 3DS 2.x Frictionless Flow;
  (NO      ) elseif ((6) **tds_status** == CReqForm?) then (YES)
  #Plum :(7) Create CReq HTML Page\nwhich redirects to ACS\n3DS 2.x Challenge Flow\nto be applied\n\nSee 3DS 2.X Challenge Flow;
  (NO      ) elseif ((8) **tds_status** == PaReqForm?) then (YES)
  #Plum :(9) Create PaReq HTML Page\nwhich redirects to ACS\nПроцесс аутентификации 3DS 1.0.2\nto be applied\n\nSee Процесс аутентификации 3DS 1.0.2;
  endif
  (NO      )elseif ((10) **html** field is present) then (YES)
  #Plum :(11) Return content of the\n**html** field to the Payeras is \n(3DS 2.x or 1.0.2 to be applied)\n\nSee Simplified authentication flow;
  else (NO)
  endif
  backward:(12) Send new\n**/api/v2/status** request\nProcess\n**/api/v2/status** response;
  endwhile (YES)
  :(13) Show result page to the Payer;
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  |<#Plum>| Connecting and other party |
  | | Other Party |
  endlegend
  @enduml

Присоединяющаяся сторона должна реализовать все шаги, отмеченные зелёным и фиолетовым цветом. Ниже приведены описания шагов со ссылками на API-команды в соответствии с номером шага.

| (1) Для реализации запроса статуса заказа см. :ref:`/api/v2/status/</api/v2/status/>`. Статус следует запрашивать несколько раз с интервалом 3-5 секунд до получения финального статуса в ответе.
| (5) Если tds_status равен MethodUrlFrame, см. :ref:`Frictionless 3DS 2.x<3ds_2x_frictionless_flow_overview>`.
| (7) Если tds_status имеет значение CReqForm, см. :ref:`3DS 2.X Challenge<3ds_2x_challenge_flow_overview>`.
| (9) Если tds_status равен PaReqForm, см. :ref:`3DS 1.0.2 Authentication<3ds_102_authentication_flow_overview>`.
| (11) Если параметр tds_status отсутствует, но присутствует поле html, см. :ref:`Simplified authentication<simplified_authentication_flow_overview>`.
| (12) То же, что и в пункте (1).

.. _Сценарий без 3DS Overview:

Сценарий без 3DS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Транзакция должна считаться non3D (без аутентификации 3DS), если соблюдены все условия:

| 1. Были выполнены шаги 1-2-(12)-13 :ref:`Схемы принятия решений 3DS<3ds_decision_making_scheme_overview>`.
| 2. Отсутствие параметров :code:`tds_status`, :code:`html` и :code:`redirect-to`.
| 3. Транзакция получила финальный статус (approved, declined, error, filtered).

.. note:: Транзакции со статусом «unknown» могут показываться как транзакции, прошедшие 3DS, так и как транзакции без прохождения 3DS. Детальнее о статусах транзакций см. :ref:`Статусы</api/v2/status/>`.

.. _3ds_2x_frictionless_flow_overview:

Процесс 3DS 2.x.0 Frictionless
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  <style>
  activityDiagram {
    diamond {
      BackgroundColor #Turquoise
    }
  }
  document {
     BackgroundColor #fcfcfc
  }
  </style>
  title Процесс 3DS 2.x.0 Frictionless
  start
  #Turquoise:(1) Send **/api/v2/status/** API request;
  #Turquoise:(2) Process **/api/v2/status/** response.
  Gather:
  **tds-method-url-frame-3ds-server-trans-id**
  **tds-method-url-frame-3ds-method-url**;
  if ((3) **tds-method-url-frame-3ds-method-url** is present) then (yes)
      #Turquoise:(4) The Connecting Party constructs **3DS Method HTML Page**\ncontaining hidden iframe and upload **3DS Method Result HTML Form**\nusing the parameters received on the previous steps\nand providing **threeDSMethodNotificationURL**;
      #Turquoise:(5) HTML Page, once rendered, is automatically submitted
      into iframe (using HTML Page target attribute);
      fork
          note left
          **iframe** lifecycle
          end note
          :(6) Payer's iframe gets redirected to
          **tds-method-url-frame-3ds-method-url**
          URL (Issuer ACS);
          :(7) Issuer ACS collects Payer Identity Data from browser;
          :(8) Issuer ACS notifies (using HTTP POST)
          **threeDSMethodNotificationURL** on completion;
          #Turquoise:(9) When notification is received gather **threeDSMethodData**.
          Base64Decode it and check **threeDSServerTransID**;
          #Turquoise:(10) Save **threeDSCompInd=Y** for the current Transaction;
          #Turquoise:(11) Return **3DS Method Done HTML Page**;
      fork again
          note left
          **3DS Method HTML Page** lifecycle
          end note
          repeat
              #Turquoise:(12) Check if Issuer ACS notification
              is received from iframe internal JavaScript;
          repeat while ((13) notification is recieved OR timeout exceeded?) is (no)
          -> (yes);
          if ((14) timeout exceeded?) then (yes)
              #Turquoise:(15) Save **threeDSCompInd=N**
              for the current Transaction;
          else (no)
          endif
          :(16) After executing 3ds method\nsend data to connecting party's server;
     end fork
      else (no)
          #Turquoise:(17) Save **threeDSCompInd=U**
          for the current Transaction;
  endif
  #Turquoise:(18) Send **api/3ds/v1/upload-method-url-result/** request
  with the collected Payer's data and **threeDSCompInd**,
  Payer's browser info and **notificationURL**
  which is to be used further in the Challenge Flow
  (see Схема прохождения 3DS and 3DS 2.X Challenge Flow).;
  #Turquoise:(19) Send **/api/v2/status/** API request
  Process **/api/v2/status/** response and follow **Схема прохождения 3DS**.;
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  | | Other Party |
  endlegend

Подключенная сторона должна реализовать все шаги, отмеченные зеленым цветом. Ниже приведены описания шагов со ссылками на конкретные API-команды в соответствии с ID шага:

| (1) Для реализации запроса статуса заказа см. :ref:`/api/v2/status/</api/v2/status/>`. Статус следует запрашивать несколько раз с интервалом 3-5 секунд до получения финального статуса в ответе.
| (2) То же, что и в пункте (1).
| (4) О создании HTML-страницы 3DS Method см. :ref:`пример ниже<frictionless_3ds_method_html_page_overview>`.
| (9) Для обработки 3DS Method Notification см. :ref:`Обработка уведомления 3DS Method<frictionless_3ds_method_process_3ds_overview>`.
| (11) Для построения HTML-страницы 3DS Method Done см. :ref:`example<frictionless_3ds_method_done_html_page_overview>`.
| (18) Для загрузки результата method url см. :ref:`/api/3ds/v1/upload-method-url-result/</api/3ds/v1/upload-method-url-result/>`.
| (19) То же, что и в пункте (1).

.. _frictionless_3ds_method_html_page_overview:

Пример HTML-страницы 3DS Method
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Приведенный ниже пример HTML-страницы 3DS Method выполняет инициацию 3DS Method через iframe и удерживает браузер плательщика до завершения 3DS Method на сервере Подключенной стороны. После завершения или по истечении тайм-аута Подключенная сторона должна выполнить следующие шаги согласно Схеме принятия решений 3DS и перенаправить браузер плательщика на соответствующий URL (либо Challenge Flow, либо страницу результата платежа). Стандартное значение тайм-аута — 30 сек.

HTML-страница 3DS Method состоит из следующих параметров:

.. list-table::
   :widths: 35, 65
   :header-rows: 1
   :class: longtable

   * - Параметр
     - Описание
   * - :code:`tds-method-url-frame-3ds-method-url`
     - URL ACS 3DS Method, полученный Подключенной стороной в ответе :ref:`/api/v2/status/</api/v2/status/>`.
   * - :code:`tdsMethodUploadUrl`
     - URL Подключенной стороны, на который приходит результат после завершения процесса.
   * - :code:`threeDSMethodData`
     - Значение JSON, содержащее :code:`threeDSServerTransID` и :code:`threeDSMethodNotificationURL`. Ниже описано, как :ref:`сформировать threeDSMethodData<frictionless_3ds_method_html_page_threeDSMethodData_overview>`.

.. _frictionless_3ds_method_html_page_threeDSMethodData_overview:

**Формирование threeDSMethodData**

Для того чтобы **сформировать threeDSMethodData**, Подключенная сторона должна использовать следующие параметры.

.. list-table::
   :widths: 30, 80
   :header-rows: 1
   :class: longtable

   * - Параметр
     - Описание
   * - :code:`threeDSServerTransID`
     - | Универсальный уникальный идентификатор транзакции, присвоенный 3DS-сервером для идентификации отдельной транзакции.
       | Получается в ответе :ref:`/api/v2/status/</api/v2/status/>` как параметр :code:`tds-method-url-frame-3ds-server-trans-id`.
   * - :code:`threeDSMethodNotificationURL`
     - URL, на который придет уведомление о завершении 3DS Method от ACS. Подключенная сторона несет ответственность за предоставление корректного threeDSMethodNotificationURL. Обычно, когда Подключенная сторона получает любой запрос на этот URL, она должна вернуть :code:`3DS Method Done HTML Page` (см. :ref:`пример ниже<frictionless_3ds_method_done_html_page_overview>`).

**Пример формирования threeDSMethodData**

1. **Сформируйте JSON** threeDSMethodData.

.. code-block:: none

  {"threeDSServerTransID":"3d671629-a410-4a5d-9288-b38ceadd41f2","threeDSMethodNotificationURL":"https://connectingparty.com/3ds-method-complete/"}

2. Примените кодирование base64 url к результирующему JSON.

.. code-block:: none

  eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNkNjcxNjI5LWE0MTAtNGE1ZC05Mjg4LWIzOGNlYWRkNDFmMiIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL21lcmNoYW50LmNvbS8zZHMtbWV0aG9kLWNvbXBsZXRlLyJ9

**Генерация Fingerprint**

3DS Method может опционально использоваться эмитентами для сбора отпечатков браузера (fingerprints) с помощью JavaScript. Это делается путем загрузки URL в скрытом iframe перед аутентификацией. Этот iframe выполнит JavaScript-код для снятия отпечатка, после чего отправит POST-запрос на заранее определенный URL запрашивающей стороны. Результат снятия отпечатка 3DS Method привязывается к аутентификации через :code:`threeDSServerTransID`.

.. code-block:: js

  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**:

.. code-block:: html

  <!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>

.. _frictionless_3ds_method_process_3ds_overview:

Обработка уведомления 3DS Method
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Когда 3DS Method завершен, Подключенная сторона получает :code:`HTTP POST` запрос на :ex:`threeDSMethodNotificationURL` с данными :code:`threeDSMethodData`, которые содержат :code:`threeDSServerTransID` (в JSON с кодировкой base64).

1. Получите :code:`threeDSMethodData`.

.. code-block:: js

  threeDSMethodData=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNkNjcxNjI5LWE0MTAtNGE1ZC05Mjg4LWIzOGNlYWRkNDFmMiJ9Cg

2. Примените декодирование base64 url для получения JSON, содержащего :code:`threeDSServerTransID`.

.. code-block:: json

  {"threeDSServerTransID":"3d671629-a410-4a5d-9288-b38ceadd41f2"}

.. _frictionless_3ds_method_done_html_page_overview:

Пример HTML-страницы 3DS Method Done
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: html

  <!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_2x_challenge_flow_overview:

Процесс 3DS 2.x.0 Challenge
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  <style>
  document {
     BackgroundColor #fcfcfc
  }
  </style>
  title Процесс 3DS 2.x.0 Challenge
  start
  #Turquoise:(1) Send **/api/v2/status/** API request;
  #Turquoise:(2) Process **/api/v2/status/** response.
  Gather:
  **tds-creq-form-creq**
  **tds-creq-form-acs-url**;
  #Turquoise:(3) Construct CReq HTML Page based on the gathered parameters.
  Add **threeDSSessionData** with the custom data
  in the format: Max length: 1024 bytes, format: Alphanumeric,
  base64url encoded without padding.;
  #Turquoise:(4) Return CReq HTML Page to Payer's browser;
  :(5) CReq Page gets redirected to ACS URL **tds-creq-form-acs-url**.
  Payer passes 3DS Challenge Verification.
  ACS return CRes Page.
  CRes Page gets submitted to **notificationURL**;
  #Turquoise:(6) Process CRes Page parameters.
  Gather parameters:
  **cres**
  **threeDSSessionData**;
  #Turquoise:(7) Send HTTP POST **/api/3ds/v1/upload-cres-result/** API Request
  providing **cres**, **orderid=paynet-order-id**;
  #Turquoise:(8) Send **/api/v2/status/** API request
  Process **/api/v2/status/** response and follow **Схема прохождения 3DS**.;
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  | | Other Party |
  endlegend

| (1) Для реализации запроса статуса заказа см. :ref:`/api/v2/status/</api/v2/status/>`. Статус следует запрашивать несколько раз с интервалом 3-5 секунд до получения финального статуса в ответе.
| (2) То же, что и в пункте (1).
| (3) О создании HTML-страницы CReq см. :ref:`пример<creqform_example_overview>`.
| (5) О реализации редиректа CRes см. :ref:`CRes redirect<cres_redirect>`.
| (7) Для загрузки результата CRes см. :ref:`/api/3ds/v1/upload-cres-result/</api/3ds/v1/upload-cres-result/>`.
| (8) То же, что и в пункте (1).

.. _creqform_example_overview:

Пример HTML-страницы CReq
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML-страница CReq перенаправляет браузер плательщика на URL ACS-сервера, указанный в параметре :code:`tds-creq-form-acs-url`. Результирующее значение CRes будет возвращено от ACS на :code:`notificationURL`, предоставленный Подключенной стороной в запросе :ref:`/api/3ds/v1/upload-method-url-result/` во время процесса 3DS 2.x.0 Frictionless.

.. list-table::
  :widths: 20 60 20
  :header-rows: 1
  :class: longtable

  * - Поле
    - Описание
    - Необходимость
  * - :code:`creq`
    - Данные ACS 3DS CReq, полученные Подключенной стороной в ответе :ref:`/api/v2/status/</api/v2/status/>`. То же, что и tds-creq-form-creq.
    - Обязательно
  * - :code:`threeDSSessionData`
    - значение, которое будет отправлено обратно в CRes на :ex:`notificationURL` в конце процесса. Максимальная длина: 1024 байта, формат: буквенно-цифровой, кодировка Base64url без дополнения (padding).
    - Опционально

.. code-block:: html

  <!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_102_authentication_flow_overview:

Процесс аутентификации 3DS 1.0.2
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  <style>
  document {
     BackgroundColor #fcfcfc
  }
  </style>
  title Процесс аутентификации 3DS 1.0.2
  start
  #Turquoise:(1) Send **/api/v2/status/** API request;
  #Turquoise:(2) Process **/api/v2/status/** response.
  Gather:
  **tds-pareq-form-pareq**
  **tds-pareq-form-acs-url**;
  #Turquoise:(3) Construct PAReq HTML Page based on the gathered parameters.
  Add **TermUrl** where the Payer gets redirected back with PARes data submitted.
  Add **MD** with the custom data which is be posted back.;
  #Turquoise:(4) Return PAReq HTML Page to Payer's browser;
  :(5) PaReq Page gets redirected to ACS URL **tds-pareq-form-acs-url**;
  :(6) Payer passes 3DS Challenge Verification;
  :(7) ACS returns PARes Page;
  :(8) PaRes Page gets submitted to the **TermUrl**;
  #Turquoise:(9) Process PARes Page parameters.
  Gather parameters:
  **PaRes**
  **MD**;
  #Turquoise:(10) Send HTTP POST **/api/3ds/v1/upload-pares-result/** API Request
  providing **paRes**, **orderid=paynet-order-id**;
  #Turquoise:(11) Send **/api/v2/status/** API request
  Process **/api/v2/status/** response and follow **Схема прохождения 3DS**.;
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  | | Other Party |
  endlegend

| (1) Для реализации запроса статуса заказа см. :ref:`/api/v2/status/</api/v2/status/>`. Статус следует запрашивать несколько раз с интервалом 3-5 секунд до получения финального статуса в ответе.
| (2) То же, что и в пункте (1).
| (3) О создании HTML-страницы PaReq см. :ref:`пример<pareqform_example_overview>`.
| (5) О реализации редиректа PaRes см. :ref:`PaRes redirect<pares_redirect>`.
| (10) Для загрузки результата PaRes см. :ref:`/api/3ds/v1/upload-pares-result/<api-3ds-v1-upload-pares-result>`.
| (11) То же, что и в пункте (10).

.. _pareqform_example_overview:

Пример HTML-страницы PaReq
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HTML-страница PaReq перенаправляет браузер плательщика на URL ACS-сервера, указанный в параметре :code:`tds-pareq-form-acs-url`.

HTML-страница PaReq состоит из следующих параметров:

.. list-table::
  :widths: 20 60 20
  :header-rows: 1
  :class: longtable

  * - Поле
    - Описание
    - Необходимость
  * - :code:`tds-pareq-form-acs-url`
    - URL ACS 3DS PaReq, полученный Подключенной стороной в ответе :ref:`/api/v2/status/</api/v2/status/>`.
    - Обязательно
  * - :code:`MD`
    - Данные Подключенной стороны, которые возвращаются на вашу страницу завершения.
    - Опционально
  * - :code:`PaReq`
    - Данные ACS 3DS PaReq, полученные Подключенной стороной в ответе :ref:`/api/v2/status/</api/v2/status/>`. То же, что и tds-pareq-form-pareq.
    - Обязательно
  * - :code:`TermURL`
    - URL страницы завершения, на которую плательщик перенаправляется обратно с переданными данными PaRes.
    - Обязательно

.. code-block:: html

  <!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>

.. _simplified_authentication_flow_overview:

Упрощённый процесс аутентификации
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  <style>
  document {
     BackgroundColor #fcfcfc
  }
  activitydiagram {
  diamond {
   BackgroundColor #Turquoise
   }
  }
  </style>
  title Упрощённый процесс аутентификации
  start
  #Turquoise:(1) Send **/api/v2/status/** API request;
  #Turquoise:(2) Process **/api/v2/status/** response;
  fork
  #Turquoise:(3)Gather **html** parameter;
  #Turquoise:(4) Return content from **html** parameter to the Payer's browser as is;
  forkagain
  #Turquoise:(5)Gather **redirect-to** parameter;
  #Turquoise:(6)Redirect Payer to redirect URL (value of redirect-to parameter);
  endfork
  :(7) Payer's browser gets redirected to ACS and Payer passes either 3DS 1.0.2 or 3DS 2.X flow.;
  :(8) Payer's browser gets redirected back to **redirect_url** provided in the initial **api/v2/sale/** request.;
  #Turquoise:(9) Process Payer's Browser final redirect to **redirect_url**.;
  #Turquoise:(10) Return Wait HTML Page to the Payer's browser;
  fork
  note left
               **Wait HTML Page** lifecycle
  end note
  repeat
  #Turquoise: (11) Request Connecting Party Server on the status of the transaction;
  #Turquoise: (12) Process transaction status;
  repeat while ((13) Received finished status\n(approved, declined, error, filtered or unknown)?) is (no)
  -> (yes);
  #Turquoise:(14) Redirect Payer's browser to the result page;
  fork again
  note left
               **Connecting Party Server** lifecycle
  end note
  repeat
  #Turquoise:(15) Send **/api/v2/status/** API request;
  #Turquoise:(16) Process **/api/v2/status/** response;
  repeat while ((17) Received final status from "Payneteasy") is (no)
  -> (yes);
  #Turquoise:(18) Save transaction status;
  end fork
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  | | Other Party |
  endlegend


| (1) Для реализации запроса статуса заказа см. :ref:`/api/v2/status/</api/v2/status/>`. Статус следует запрашивать несколько раз с интервалом 3-5 секунд до получения финального статуса в ответе.
| (2) То же, что и в пункте (1).
| (6) О реализации финального редиректа см. :ref:`Final redirect<final_redirect>`.
| (7) HTML-страница ожидания на стороне Подключенной стороны может иметь индивидуальный дизайн и должна взаимодействовать с сервером Подключенной стороны, как показано на диаграмме.
| (12) и (13) То же, что и в пункте (1).

.. _alternative_cardholder_authentication:

Альтернативная аутентификация держателя карты
-----------------------------------------------------------------------------------------

Платежный шлюз поддерживает альтернативные методы аутентификации держателя карты, если карта не участвует в 3DS (отрицательный ответ 3DS enrollment). Одним из таких методов является проверка случайной суммы. В этом методе Платежный шлюз инициирует дополнительную транзакцию преавторизации для удержания случайной небольшой суммы на счету держателя карты и отправляет специальную форму для ввода плательщиком удержанной суммы. Если сумма указана верно, Платежный шлюз продолжает обработку первоначальной транзакции. Удержание небольшой суммы отменяется автоматически.

Общая диаграмма для транзакций через форму
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 2
  skinparam ParticipantPadding 30
  actor Payer as Customer
  participant "Connecting Party" as Merchant
  participant "Payment Gateway" as g
  autonumber
  Customer -> Merchant: Checkout
  activate Merchant
  == Purchase payment request ==
  Merchant -> g: Request Initiating
  activate g
  g --> Merchant: Redirect-url, Order ID
  deactivate g
  Merchant -> Customer: Provide redirect-url to Payer's browser
  activate Customer
  Customer -> g: GET redirect-url
  deactivate Customer
  activate g
  g -> Customer: Платёжная Форма
  deactivate g
  activate Customer
  Customer -> g: Submit Form
  deactivate Customer
  activate g
  g -> g: Transaction processing
  g -> g: 3DS Enrollment
  g -> g: Random Sum Processing
  g -> Customer: Redirecting to the Random Sum Check html form
  deactivate g
  activate Customer
  Customer -> g: The cardholder provides auth data
  deactivate Customer
  activate g
  g -> g: Auth Data Validating
  group alt
  == Receive Connecting Party Callback ==
  Merchant <- g: Сallback with final status
  g <-- Merchant: HTTP 200
  deactivate g
  == Order Status Request ==
  Merchant -> g: api/v2/status
  activate g
  g --> Merchant: Response \nstatus, order-stage
  deactivate g
  end
  Merchant --> Customer: Show result
  deactivate Merchant
  deactivate Customer

| (2) См. соответствующий Use-Case для получения подробностей о конкретной API-команде для инициации транзакции.
| (13) Для имплементации обратного вызова с обработкой финального статуса см.:ref:`Обратный вызов Присоединяющейся Стороны<merchant_callbacks>`.
| (15) Пожалуйста, см. :ref:`Status List<status_list>` для получения дополнительной информации о финальных статусах.



Общая диаграмма для прямых интеграций
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 1
  skinparam maxmessagesize 1200
  skinparam sequenceParticipant underline
  actor Payer
  participant "Connecting Party" as A
  participant "Payment Gateway" as B
  autonumber
  Payer -> A: Checkout
  activate A
  A -> B: Payment Initiating
  activate B
  B --> A: Order ID
  B -> B: Transaction processing
  group loop
  A -> B: Status Request
  B --> A: Non-Final Status
  end
  B -> B: 3DS Enrollment
  B -> B: Random Sum Processing
  A -> B: Status Request
  B -> A: Response with Random Sum Check html form
  A -> Payer: Redirecting to the Random Sum Check html form
  deactivate B
  activate Payer
  Payer -> B: Cardholder provides auth data
  deactivate Payer
  activate B
  B -> B: Auth Data Validating
  group alt
  group Get Final Status
  == Receive Connecting Party Callback ==
  A <- B: Callback with Final Status
  A --> B: HTTP 200
  deactivate B
  == Order Status Request ==
  A -> B: Get Status by Order ID
  activate B
  B --> A: Response status, \norder-stage
  deactivate B
  end
  A --> Payer: Show result
  deactivate A

| (2) См. соответствующий Use-Case для получения подробностей о конкретной API-команде для инициации транзакции.
| (9) Запрос статуса продолжается параллельно все время, начиная с шага 5.
| (11) Для обработки обратного вызова с окончательным статусом заказа см.:ref:`Обратный вызов Присоединяющейся Стороны<merchant_callbacks>`.
| (13) Пожалуйста, см. :ref:`Status List<status_list>` для получения дополнительной информации о финальных статусах.

.. ifconfig:: "doc.payneteasy.com" in site_link

   ----

   .. admonition:: See also
      :class: related-cross-link

      `3DS Adapter — unobtrusive Strong Customer Authentication → <https://payneteasy.com/solutions/3ds_adapter>`_

.. ifconfig:: "doc.payneteasy.ru" in site_link

   ----

   .. admonition:: См. также
      :class: related-cross-link

      `Платформа Payneteasy: 3DS, токенизация, безопасность → <https://payneteasy.ru/payment_platform>`_