.. _3ds_server_to_server_sale:

Server-to-Server Sale
##########################################

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

Introduction
------------------------------------

| Sale is a type of transaction, in which Payer receives goods or services from Connecting Party in exchange for money or other assets. In this use case Server-to-server Sale, card data is transferred directly in initiating request.
|
| See terms definitions (Connecting Party, 3DS Method, etc) in :ref:`Glossary<glossary>`.


Sale Flow
---------------------------------
.. uml::
    :align: center

    skinparam roundcorner 20
    skinparam sequenceArrowThickness 1
    skinparam maxmessagesize 1200
    skinparam sequenceParticipant underline
    actor Payer
    participant "Connecting Party" as A
    participant "Payneteasy" as B
    autonumber
    Payer -> A: Checkout
    activate A
    A -> B: /api/v2/sale/
    activate B
    B --> A: Order ID
    B -> B: Process\nSale
    hnote over Payer,B : See 3DS Decision Making Schema
    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: Final Status
    deactivate B
    end
    A --> Payer: Show result
    deactivate Payer
    deactivate A


| (2) To implement sale request see :ref:`/api/v2/sale/</api/v2/sale/>`. By default, 3DS is being initiated and performed by Payment Gateway with :ref:`Simplified authentication flow<simplified_authentication_flow_sale>`. See :ref:`3DS Decision Making Schema<3ds_server_to_server_sale_reference>`.
| (5) To implement callback with final status handling see :ref:`Connecting Party Callback<merchant_callbacks>`.
| (7) 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.

.. _3ds_server_to_server_sale_reference:

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

.. uml::
  :align: center

    <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);
      switch ((3) **html** and **redirect-to** field is present)
      case (YES)
     #Plum :(4) Create Wait HTML Page\nwhich redirects to result page\n(3DS 2.x or 1.0.2 to be applied)\n\nSee Simplified authentication flow;
      case (NO)
    endswitch
      backward:(5) Send new\n**/api/v2/status** request\nProcess\n**/api/v2/status** response;
      endwhile (YES)
      :(6) Show result page to the Payer;
      stop
      legend left
      =Legend
      | Color | Implementation responsibility |
      |<#Turquoise>| Connecting party |
      |<#Plum>| Connecting and other party |
      | | Other Party |
      endlegend

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.
| (4) If html and redirect-to fields are present, see :ref:`Simplified authentication flow with html page<simplified_authentication_flow_sale>`.
| (5) The same as point (1).

.. note:: The :ref:`3DS decision making schema<3ds_server_to_server_sale_reference>` is showcasing 3DS being initiated and performed by Payment Gateway. For other 3DS implementation scenarios, please see :ref:`3DS Overview<3ds_implementation_scenarios>` and contact support manager.


.. _non_3d_sale:

Non3D Flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sale transaction should be considered as non3D (no 3DS authentication) if all conditions are met:

| 1. Steps 1-2-(5)-6 of :ref:`3DS decision making schema<3ds_server_to_server_sale_reference>`  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/>`.

.. _simplified_authentication_flow_sale:

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.
  Gather:
  **html** parameter;
  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;
  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
  #Turquoise:(15) Send **/api/v2/status/** API request;
  #Turquoise:(16) Process **/api/v2/status/** response \nand follow **3DS Decision Making Schema** to analyze status response;
  end fork
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  | | Other Party |
  endlegend

| (1) and (2) To implement order status request see :ref:`/api/v2/status/</api/v2/status/>`.
| (9) To implement final redirect see :ref:`Final redirect<final_redirect>`.
| (10) The HTML wait page on Connecting Party side can have custom design and should communicate with Connecting Party server as described on the diagram.
| (15) and (16) The same as point (1) and (2).