.. _3ds_overview_reference:

3DS Overview
########################

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code



.. _3ds_flow_overview_reference:

Payneteasy 3DS Flow
----------------------------------------------------

Reference:

|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 is a protocol designed to be an additional security layer for online credit and debit card transactions.
| 3-D Secure protocol has two main versions.

| 1.0 – which was introduced in 2001 and is still used by some acquirers (Services based on this protocol were adopted by different card schemes giving it different names: Verified by Visa or Visa Secure used by Visa, SecureCode used by Mastercard, ProtectBy used by Discover, J/Secure used by JCB International, American Express SafeKey used by American Express.
| 2.X – which was introduced in 2016 to strengthen and supersede the version 1.0 and it was aimed at complying with the new EU authentication requirements and resolving some short-comings of the original protocol.

Despite low level message exchange differences in the essence protocol version 2.X differs from 1.0 by introducing and option for the issuer of the card to perform an automatic risk assessment based on the additional contextual data sent from the payer browser or mobile app, whereas 1.0 version always requires payer to pass an authentication challenge. Correspondingly (and according to EMVCo spec) protocol version 2.X includes Frictionless flow (gathering contextual data and performing risk assessment) and Challenge flow (passing authentication challenge). The normal Payer’s web flow which passes 3DS 2.X Authentication can be illustrated as below.

1. Payers fill out a payment form provided by Connection Party or Payment Gateway side and sends data.

.. image:: /_static/images/3ds_server_to_server_sale_flow/payment_form.png
  :alt: Payment Form
  :align: center
  :width: 550

|

.. note:: For Transfer transactions, payment form might look as described below.

.. image:: /_static/images/3ds_server_to_server_transfer_flow/transfer_flow.png
  :alt: Payment Form
  :align: center
  :width: 550

|

2. Contextual data is gathered and sent to the Issuer in a hidden process within the browser (Frictionless flow).

.. image:: /_static/images/3ds_server_to_server_sale_flow/wait_form.png
  :alt: Wait Form
  :align: center
  :width: 550

|

3. If Issuer finds the transaction risky Payer’s browser gets redirected to the Issuer web page to pass authentication challenge (Challenge flow).

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

|

4. When Payer passes checks the payment authorization is made saving the details related to the 3DS Authentication on the acquirer side.

.. image:: /_static/images/3ds_server_to_server_sale_flow/wait_form.png
  :alt: Wait Form
  :align: center
  :width: 550

|

5. Payer’s browser gets redirected to the Connecting Party website to the resultant page.

.. image:: /_static/images/3ds_server_to_server_sale_flow/finish_form.png
  :alt: Finish Form
  :align: center
  :width: 550

|

Due to the fact that both protocol versions still used the Connecting party have to deal with both of them as well as specific integrations when acquirer handles 3D Secure communication on its end. For this purpose, Payment Gateway provides universal/generic approach based on the API commands which allow the Connecting party to handle all mentioned cases. The Connecting Party has to start with the 3DS Decision Making Schema of the relevant Use-Case which in turn refers to the more detailed diagram describing specifics of the data handling and Payer’s browser redirects related to the corresponding 3DS flow.

.. _3ds_implementation_scenarios:

3DS Implementation Scenarios
------------------------------------------------------

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

   * - Implementation Scenario
     - Instructions
   * - 3DS is not initiated (non3D).
     - 3DS Authentication is not initiated. Follow 3DS Decision Making Schema of relevant Use-Case and implement Non3D Flow.
   * - 3DS is initiated and performed by Connecting Party (for PSPs and Acquirers).
     - 3DS Authentication is initiated and performed by Connecting Party, results are uploaded to Payment Gateway in initial request. Follow 3DS Decision Making Schema of relevant Use-Case and implement Non3D Flow (3DS is performed before the initial request to Payment Gateway).
   * - 3DS is initiated by Payment Gateway and performed on Connecting Party side.
     - 3DS Authentication is initiated by Payment Gateway. For 3DS 1.0.2, Payer Authentication is performed on Connecting Party side, results are uploaded to Payment Gateway. For 3DS 2.x, 3DS Method and Challenge are performed on Connecting Party side, results are uploaded to Payment Gateway. Additional fields for 3DS Method can be provided by Connecting Party in initial request to speed up the process for 3DS 2.x (tds_status=MethodUrlFrame will be skipped if 3DS Method is not supported by ACS). Follow 3DS Decision Making Schema of relevant Use-Case and implement all 3DS Flows.
   * - 3DS is initiated and performed by Payment Gateway.
     - 3DS Authentication is initiated by Payment Gateway, all 3DS scenarios are performed on Payment Gateway side. Follow 3DS Decision Making Schema of relevant Use-Case, implement Simplified Authentication Flow (ignore tds_status parameter presence, use html or redirect-to parameters to redirect the Payer to Payment Gateway) and Non3D Flow (if Payer's card is not enrolled or processing is Non3D).

.. _3ds_decision_making_scheme_overview:

3DS Decision Making Schema
-----------------------------------------

.. uml::
  :align: center

  @startuml
  <style>
  activityDiagram {
  BackgroundColor #Turquoise
    diamond {
      BackgroundColor #Turquoise
    }
  }
  document {
     BackgroundColor #fcfcfc
  }
  </style>
  title 3DS Decision Making Schema
  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\n3DS 1.0.2 Authentication Flow\nto be applied\n\nSee 3DS 1.0.2 Authentication Flow;
  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

Connecting party has to implement all steps marked in green and purple. Below are the description for steps which reference specific API commands according to the step ID:

| (1) To implement order status request see :ref:`/api/v2/status/</api/v2/status/>`. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
| (5) If tds_status is MethodUrlFrame see :ref:`Frictionless 3DS 2.x<3ds_2x_frictionless_flow_overview>`.
| (7) If tds_status is CReqForm see :ref:`3DS 2.X Challenge<3ds_2x_challenge_flow_overview>`.
| (9) If tds_status is PaReqForm see :ref:`3DS 1.0.2 Authentication<3ds_102_authentication_flow_overview>`.
| (11) If tds status is not present, but html field is present, see :ref:`Simplified authentication<simplified_authentication_flow_overview>`.
| (12) The same as point (1).

.. _Non3D Flow Overview:

Non3D Flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Transaction should be considered as non3D (no 3DS authentication) if all conditions are met:

| 1. steps 1-2-(12)-13 of :ref:`3DS decision making schema<3ds_decision_making_scheme_overview>`  were followed.
| 2. :code:`tds_status`, :code:`html` and :code:`redirect-to` parameters were not present.
| 3. transaction received final status (approved, declined, error, filtered).

.. note:: Please note that transaction status "unknown" might appear for both 3DS and non3D transactions. See details in :ref:`Statuses</api/v2/status/>`.

.. _3ds_2x_frictionless_flow_overview:

3DS 2.x.0 Frictionless Flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  <style>
  activityDiagram {
    diamond {
      BackgroundColor #Turquoise
    }
  }
  document {
     BackgroundColor #fcfcfc
  }
  </style>
  title 3DS 2.x.0 Frictionless Flow
  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 Decision Making Schema and 3DS 2.X Challenge Flow).;
  #Turquoise:(19) Send **/api/v2/status/** API request
  Process **/api/v2/status/** response and follow **3DS Decision Making Schema**.;
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  | | Other Party |
  endlegend

Connecting party has to implement all steps marked in green. Below are the description for steps which reference specific API commands according to the step ID:

| (1) To implement order status request see :ref:`/api/v2/status/</api/v2/status/>`. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
| (2) The same as point (1).
| (4) To construct 3DS Method HTML page see :ref:`example<frictionless_3ds_method_html_page_overview>` below.
| (9) To process 3DS Method Notification see :ref:`Process 3DS Method Notification<frictionless_3ds_method_process_3ds_overview>`.
| (11) To construct 3DS Method Done HTML page see :ref:`example<frictionless_3ds_method_done_html_page_overview>`.
| (18) To upload method url result see :ref:`/api/3ds/v1/upload-method-url-result/</api/3ds/v1/upload-method-url-result/>`.
| (19) The same as point (1).

.. _frictionless_3ds_method_html_page_overview:

3DS Method HTML Page Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

3DS Method HTML Page example below performs 3DS Method initiation through iframe technique and holding of the Payer's browser until the 3DS Method is not finished on the Connecting Party server. Once it is finished or timeout is reached Connecting Party has to follow the next steps following 3DS Decision Making Schema and redirect Payer's browser to the corresponding URL (either Challenge Flow or payment result page). Normal timeout value is 30 sec.

3DS Method HTML Page consists of the following parameters:

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

   * - Parameter
     - Description
   * - :code:`tds-method-url-frame-3ds-method-url`
     - ACS 3DS Method URL is received by the Connecting Party in the :ref:`/api/v2/status/</api/v2/status/>` response.
   * - :code:`tdsMethodUploadUrl`
     - Connecting Party's URL, where the result comes after the completion of the flow.
   * - :code:`threeDSMethodData`
     - JSON value containing :code:`threeDSServerTransID` and :code:`threeDSMethodNotificationURL`. See below how to :ref:`construct threeDSMethodData<frictionless_3ds_method_html_page_threeDSMethodData_overview>`.

.. _frictionless_3ds_method_html_page_threeDSMethodData_overview:

**Construct threeDSMethodData**

In order to **construct threeDSMethodData** the Connecting Party has to use the following parameters.

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

   * - Parameter
     - Description
   * - :code:`threeDSServerTransID`
     - | Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
       | Received in the :ref:`/api/v2/status/</api/v2/status/>` response as :code:`tds-method-url-frame-3ds-server-trans-id` parameter.
   * - :code:`threeDSMethodNotificationURL`
     - The URL that will receive the notification of 3DS Method completion from the ACS. The Connecting Party is responsible for providing valid threeDSMethodNotificationURL. Normally when the Connecting Party receives any request on this URL is has to return :code:`3DS Method Done HTML Page` (see :ref:`example<frictionless_3ds_method_done_html_page_overview>` below).

**threeDSMethodData construction example**

1. **Construct threeDSMethodData** JSON.

.. code-block:: none

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

2. Apply base64 url encoding to resultant JSON.

.. code-block:: none

  eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNkNjcxNjI5LWE0MTAtNGE1ZC05Mjg4LWIzOGNlYWRkNDFmMiIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL21lcmNoYW50LmNvbS8zZHMtbWV0aG9kLWNvbXBsZXRlLyJ9

**Generate Fingerprint**

The 3DS Method can be optionally used by issuers to gather browser fingerprints using JavaScript. This is done by loading a URL in a hidden iframe, before the authentication. This iframe will then execute some fingerprinting JavaScript, before POST’ing to the prespecified URL belonging to the requestor. The 3DS Method fingerprint result is tied to the authentication by the :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
  }

**Construct 3DS Method HTML page example**:

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

Process 3DS Method Notification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When 3DS Method is completed, the Connecting Party receives :code:`HTTP POST` request at :ex:`threeDSMethodNotificationURL` with :code:`threeDSMethodData`, which contains :code:`threeDSServerTransID` (in base64 encoded JSON).

1. Get :code:`threeDSMethodData`.

.. code-block:: js

  threeDSMethodData=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNkNjcxNjI5LWE0MTAtNGE1ZC05Mjg4LWIzOGNlYWRkNDFmMiJ9Cg

2. Apply base64 url decoding to get JSON, which contains :code:`threeDSServerTransID`.

.. code-block:: json

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

.. _frictionless_3ds_method_done_html_page_overview:

3DS Method Done HTML Page Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. 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 Flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  <style>
  document {
     BackgroundColor #fcfcfc
  }
  </style>
  title 3DS 2.x.0 Challenge Flow
  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 Decision Making Schema**.;
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  | | Other Party |
  endlegend

| (1) To implement order status request see :ref:`/api/v2/status/</api/v2/status/>`. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
| (2) The same as point (1).
| (3) To create CReq HTML Page see :ref:`example<creqform_example_overview>`.
| (5) To implement CRes redirect see :ref:`CRes redirect<cres_redirect>`.
| (7) To upload CRes result see :ref:`/api/3ds/v1/upload-cres-result/</api/3ds/v1/upload-cres-result/>`.
| (8) The same as point (1).

.. _creqform_example_overview:

CReq HTML Page Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

CReq HTML Page redirects the Payer's browser to ACS Server URL, provided in :code:`tds-creq-form-acs-url` parameter. The result CRes value will be returned from ACS to :code:`notificationURL` provided by Connecting Party in :ref:`/api/3ds/v1/upload-method-url-result/` request during 3DS 2.x.0 Frictionless Flow.

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

  * - Field
    - Description
    - Necessity
  * - :code:`creq`
    - ACS 3DS CReq data, which received by the Connecting Party in the :ref:`/api/v2/status/</api/v2/status/>` response. The same as tds-creq-form-creq.
    - Required
  * - :code:`threeDSSessionData`
    - value which will be posted back within CRes to :ex:`notificationURL` at the end of the process. Max length: 1024 bytes, format: Alphanumeric, Base64url encoded without padding.
    - Optional

.. 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 Authentication Flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  <style>
  document {
     BackgroundColor #fcfcfc
  }
  </style>
  title 3DS 1.0.2 Authentication Flow
  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 Decision Making Schema**.;
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  | | Other Party |
  endlegend

| (1) To implement order status request see :ref:`/api/v2/status/</api/v2/status/>`. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
| (2) The same as point (1).
| (3) To construct PaReq HTML Page see :ref:`example<pareqform_example_overview>`.
| (5) To implement PaRes redirect see :ref:`PaRes redirect<pares_redirect>`.
| (10) To upload PaRes result see :ref:`/api/3ds/v1/upload-pares-result/<api-3ds-v1-upload-pares-result>`.
| (11) The same as point (10).

.. _pareqform_example_overview:

PaReq HTML Page Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

PaReq HTML Page redirects the Payer's browser to ACS Server URL, provided in :code:`tds-pareq-form-acs-url` parameter.

PaReq HTML Page consists of the following parameters:

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

  * - Field
    - Description
    - Necessity
  * - :code:`tds-pareq-form-acs-url`
    - ACS 3DS PaReq URL is received by the Connecting Party in the :ref:`/api/v2/status/</api/v2/status/>` response.
    - Required
  * - :code:`MD`
    - Connecting Party Data, which comes back to your termination page.
    - Optional
  * - :code:`PaReq`
    - ACS 3DS PaReq data, which received by the Connecting Party in the :ref:`/api/v2/status/</api/v2/status/>` response. The same as tds-pareq-form-pareq.
    - Required
  * - :code:`TermURL`
    - URL of termination page, where the Payer gets redirected back with PaRes data submitted.
    - Required

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

Simplified Authentication Flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  <style>
  document {
     BackgroundColor #fcfcfc
  }
  activitydiagram {
  diamond {
   BackgroundColor #Turquoise
   }
  }
  </style>
  title Simplified Authentication Flow
  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) To implement order status request see :ref:`/api/v2/status/</api/v2/status/>`. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
| (2) The same as point (1).
| (6) To implement final redirect see :ref:`Final redirect<final_redirect>`.
| (7) The HTML wait page on Connecting Party side can have custom design and should communicate with Connecting Party server as described on the diagram.
| (12) and (13) The same as point (1).

.. _alternative_cardholder_authentication:

Alternative cardholder authentication
-----------------------------------------------------------------------------------------

Payment Gateway supports alternative methods for cardholder authentication if card is not enrolled to 3DS (negative 3DS enrollment response). One of such methods is random sum check. In this method, Payment Gateway initiates an additional preauthorization transaction to hold a random small amount on cardholder’s account and sends a special form for the Payer to enter the amount being held. If the amount is correct, Payment Gateway continues to process the initial transaction. The small amount hold is cancelled automatically.

General diagram for form transactions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. 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: Payment Form
  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) See relevant Use-Case to get details about the exact API command to initiate transaction.
| (13) To implement callback with final status handling see :ref:`Connecting Party Callbacks<merchant_callbacks>`.
| (15) Please see :ref:`Status List<status_list>` to get more information about Final Statuses.



General diagram for direct integrations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. 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) See relevant Use-Case to get details about the exact API command to initiate transaction.
| (9) Status Request continues in parallel all the time starting from step 5.
| (11) To implement callback with final status handling see :ref:`Connecting Party Callbacks<merchant_callbacks>`.
| (13) Please see :ref:`Status List<status_list>` to get more information about Final Statuses.