.. _server_to_server_transfer:

Server-to-Server Transfer
#########################

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

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

.. _possible_transfer_use_cases:

| Transfer is a type of complex transaction that allows to move funds between bank cards (:ref:`PAN<transfer_definitions>`), card tokens (:ref:`RPI<transfer_definitions>`) and Connecting Party bank account (:ref:`deposit<transfer_definitions>`).
|
| See terms definitions (Connecting Party, 3DS Method, etc) in :ref:`Glossary<glossary>`.
|
| Possible transfer Use-Cases:

.. list-table::
   :widths: 25, 75
   :header-rows: 0
   :class: longtable

   * - PAN to PAN
     - Transfer from PAN to PAN occurs when transferring funds from one bank card to another, when specifying for each card their card numbers, and not the recurring payment id.
   * - PAN to RPI
     - Transfer from PAN to RPI occurs when funds are transferred from one bank card for which its number is indicated to another bank card for which its recurring payment id is indicated.
   * - RPI to PAN
     - Transfer from RPI to PAN occurs when funds are transferred from one bank card for which its recurring payment id is indicated to another bank card for which its number is indicated.
   * - RPI to RPI
     - Transfer from RPI to RPI occurs when transferring funds from one bank card to another, when specifying for each card their recurring payment id, and not the card number.
   * - deposit to PAN
     - Transfer from deposit to PAN occurs when funds are transferred from Connecting Party account to a bank card by its number.
   * - deposit to PRI
     - Transfer from deposit to RPI occurs when funds are transferred from Connecting Party account to a bank card by recurring payment id.

.. _transfer_definitions:


Transfer Flow
------------------

.. uml::
  :align: center

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 2
  skinparam ParticipantPadding 30
  autonumber
  actor Sender as Payer
  participant "Connecting Party" as A
  participant "Payment Gateway" as B

  Payer -> A: Checkout
  activate A
  == Transfer Request ==
  A -> B: api/v4/transfer
  activate B
  B --> A: Order ID
  B -> B: Process payment
  hnote over Payer,B : See 3DS Decision Making Schema
  group Get Final Status
  == Receive Connecting Party Callback ==
  A <- B: Сallback with final status
  B <-- A: 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 A

| (1) Transfers between cards are initiated by Sender. Transfer from Connecting Party (deposits) are initiated by Receiver, with the same transaction flow.
| (2) To implement transfer request see :ref:`/api/v4/transfer/</api/v4/transfer/>`. By default, 3DS is being initiated and performed by Payment Gateway with :ref:`Simplified authentication flow<transfer_simplified_authentication_flow>`. See :ref:`3DS Decision Making Schema<3ds_server_to_server_transfer_reference>`. For deposit to PAN and deposit to RPI cases 3DS is not initiated (flow is :ref:`non3D<Non3D_Transfer>`).
| (5) To implement callback with final status handling see :ref:`Connecting Party Callbacks<merchant_callbacks>`.
| (7) To implement order status 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_transfer_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<transfer_simplified_authentication_flow>`.
| (5) The same as point (1).

.. note:: The :ref:`3DS decision making schema<3ds_server_to_server_transfer_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.


.. _Non3D_Transfer:

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/>`.

.. _transfer_simplified_authentication_flow:

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