.. _recurring_preauth_capture_and_cancel:

Recurring Preauth, Capture and Cancel
==================================================================================

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

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

| Preauthorization is a transaction type in which bank blocks the specified amount in the Payer's card account and does not allow the cardholder to use this blocked money. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards).
|
| See terms definitions (Connecting Party, 3DS Method, etc) in :ref:`Glossary<glossary>`.
|
| Recurring (Rebill) Preauth is a type of transaction in which funds are debited from the Payer’s side to the Connecting Party’s bank account with previously saved cardholder data. Recurring preauth transaction can be initiated manually on Payer's behalf (this simplifies the payment process for the Payer) or automatically at certain intervals by Connecting Party (i.e. as a subscription model). Payer does not have to re-enter card information, Connecting Party uses Card reference ID to authorize payment. The necessity of Payer's 3DS check and submit of card security code (CVC, CVV, etc) for recurring preauth transactions is determined by bank account settings and related to Connecting Party business type.
|
| :ref:`Capture<capture_preauth>` is a transaction followed after preauth which deducts the locked amount from Payer’s card.
| :ref:`Cancel<cancel_preauth>` is opposite of Capture which cancels the deduction and returns locked amount back to Payer’s card.
|
| Recurring payments are made in three steps:
| 1. Initial payment – make initial payment to verify and authorize the Payer's card. Any transaction type with present cardholder data will work as initial payment - sale, preauth, transfer, etc.
| 2. Card registration – get Card reference ID and register Payer’s card in Payer’s profile. Card registration requires initial payment to be in :ref:`final status<status_list>`.
| 3. Recurring preauth – process recurring preauth transaction using Card reference ID.

Recurring Preauth Flow
--------------------------------------------------

.. 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
  hnote over Payer,B : Initial payment
  == Card registration ==
  A -> B: api/v2/create-card-ref/
  activate B
  activate A
  B --> A: Return Card ref ID
  deactivate B
  A -> A: Save Card ref ID to Payer's profile
  deactivate A
  == Get Card Info ==
  group Optional
  A -> B: api/v2/get-card-info/
  activate A
  activate B
  B --> A: Return Card info
  deactivate A
  deactivate B
  end
  == Recurring Preauth ==
  group Optional
  Payer -> A: Initiate Recurring Preauth
  activate A
  activate Payer
  end
  A -> A: Get Card ref ID from Payer's profile
  group Optional
  A -> Payer: Request CVV from Payer
  Payer --> A: Submit CVV
  end
  A -> B: api/v2/make-rebill-preauth/
  activate B
  B --> A: Response with Order ID
  hnote over Payer,B : See 3DS Decision Making Schema
  group Get Final Status
  == Receive 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
  group Optional
  A --> Payer: Show result
  deactivate Payer
  deactivate A
  end

.. note:: Initial payment transaction type and implementation depends on Connecting Party business model. Please contact Payneteasy support team to get relevant integration Use-Case for initial payment.

| (1) To implement Card registration and get Card reference ID see :ref:`/api/v2/create-card-ref/<api-v2-card-ref-id>`.
| (4) To implement Card information request by Card reference ID see :ref:`/api/v2/get-card-info/</api/v2/get-card-info/>`. The contents of response to this request can be used to show information about previously used card to Payer or to update Connecting Party database. This request can be made anytime if Connecting Party has Card reference ID.
| (6) Recurring payment can be initiated by Connecting Party based on internal business model or Payer’s request.
| (8, 9) Connecting Party sends request to the Payer to submit the CVV/CVC (Card Verification Value/Code), if it is required for selected processing channel.
| (10) To initiate recurring preauth transaction see :ref:`/api/v2/make-rebill-preauth/</api/v2/make-rebill-preauth/>`. By default, 3DS is being initiated and performed by Payment Gateway with :ref:`Simplified authentication flow<simplified_authentication_flow>`. See :ref:`3DS Decision Making Schema<3ds_2x_decision_making_schema_preauth>`.
| (12) To implement callback with final status handling see :ref:`Connecting Party Callbacks<merchant_callbacks>`.
| (14) 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.
| (16) Results of operation can be sent by Connecting Party based on internal business model or Payer’s request.

.. _3ds_2x_decision_making_schema_preauth:

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>`.
| (5) The same as point (1).

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

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



.. _capture_preauth:

Capture Flow
---------------------------------------------------------

.. uml::
  :align: center

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 1
  skinparam maxmessagesize 100
  skinparam sequenceParticipant underline
  actor Payer
  participant "Connecting party" as A
  participant "Payment Gateway" as B
  hnote over Payer,B : Successful Preauth Transaction
  autonumber
  == Capture ==
  group Optional
  Payer -> A: Initiate Capture
  activate Payer
  activate A
  end
  A -> B: api/v2/capture
  activate B
  B --> A: Order ID
  B -> B: Process Capture
  group Get Final Status
  == Receive Callback ==
  A <- B: Callback with Final Status
  A --> B: HTTP 200
  deactivate B
  == Order Status Request ==
  A -> B: Get Status by Order ID api/v2/status
  activate B
  B --> A: Response with Status, Order-stage
  deactivate B
  end
  group Optional
  A --> Payer: Final Status
  deactivate Payer
  deactivate A
  end


| (1) Capture can be initiated by Connecting Party based on internal business process or Payer’s request.
| (2) To implement capture request see :ref:`/api/v2/capture/</api/v2/capture/>`.
| (5) Callback for Capture will be sent only if :ex:`notify_url` was provided in initial transaction request or additional callback URL for Capture transactions is specified on the endpoint level. If :ex:`server_callback_url` was provided in initial transaction request, callback for Capture will not be sent. 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.
| (9) Final Status can be sent by Connecting Party based on internal business model or by Payer’s request.

.. _cancel_preauth:

Cancel Flow
-----------------------------------------------------

.. uml::
  :align: center

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 1
  skinparam maxmessagesize 100
  skinparam sequenceParticipant underline
  actor Payer
  participant "Connecting party" as A
  participant "Payment Gateway" as B
  hnote over Payer,B : Successful Preauth Transaction
  autonumber
  == Cancel ==
  group Optional
  Payer -> A: Initiate Cancel
  activate Payer
  activate A
  end
  A -> B: api/v2/return
  activate B
  B --> A: Order ID
  B -> B: Process Cancel
  group Get Final Status
  == Receive Callback ==
  A <- B: Callback with Final Status
  A --> B: HTTP 200
  deactivate B
  == Order Status Request ==
  A -> B: Get Status by Order ID api/v2/status
  activate B
  B --> A: Response with Status, Order-stage
  deactivate B
  end
  group Optional
  A --> Payer: Final Status
  deactivate Payer
  deactivate A
  end

| (1) Cancel can be initiated by Connecting Party based on internal business process or Payer’s request.
| (2) To implement cancel request see :ref:`/api/v2/return/</api/v2/return/>`.
| (5) Callback for Cancel will be sent only if :ex:`notify_url` was provided in initial transaction request or additional callback URL for Cancel transactions is specified on the endpoint level. If :ex:`server_callback_url` was provided in initial transaction request, callback for Cancel will not be sent. 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.
| (9) Final Status can be sent by Connecting Party based on internal business model or by Payer’s request.