.. meta::
   :description: Рекуррентная Preauth с Capture и Cancel в API Payneteasy: блокировка средств с использованием сохранённого рекуррентного ID с последующим завершением или снятием авторизации.

.. _recurring_preauth_capture_and_cancel:

Повторная предавторизация, списание и отмена
==================================================================================


.. role:: ex

.. role:: code

Введение
--------------------------------------------------

| Оплата — тип транзакции, при которой банк блокирует определённую сумму на карте Плательщика и не позволяет использовать эту сумму. Важно учесть, что блокирование средств действует в течение определённого периода (обычно это до 7 дней для дебетовых карт и до 28 дней для кредитных карт).
|
| См. определения терминов (Присоединяющаяся Сторона, 3DS Method и т.д.) в :ref:`Глоссарии<glossary>`.
|
| Повторная предавторизация (рекуррентная предавторизация) - это тип транзакции, при которой средства Плательщика блокируются на определённый период с повторным использованием ранее сохранённого средства оплаты. Повторная предавторизация может быть инициирована вручную по инициативе Плательщика (таким образом можно упростить оплату для Плательщика), либо автоматически с заданным интервалом по инициативе Присоединяющейся Стороны (например, в модели подписки). Плательщику не требуется повторно заполнять платёжные данные, Присоединяющая Сторона использует Ссылочный идентификатор (Card Reference ID) для инициации оплаты. Необходимость проведения 3DS и ввода защитного кода (CVC, CVV и т.п.) в случае оплаты картой определяется настройками счёта в Эквайере и зависит от модели бизнеса Присоединяющейся стороны.
|
| :ref:`Списание<capture_preauth>` - тип транзакции, следующий за предавторизацией, для списания предварительно заблокированных средств с карты Плательщика.
| :ref:`Отмена<cancel_preauth>` - противоположная списанию транзакция, отменяющая блокировку и возвращающая средства в свободное пользование Плательщиком.
|
| Повторная оплата совершается в 3 стадии:
| 1. Первый платёж – необходимо совершить первую оплату для проверки платёжного средства (например, карты) Плательщика. Для первого платежа подходит любой тип транзакции с платёжной информацией Плательщика - sale, preauth, transfer, и др.
| 2. Регистрация карты (или иного платёжного метода) – необходимо получить Ссылочный идентификатор (Card reference ID) и привязать его к профилю Плательщика. Регистрация платёжного метода возможна только для транзакций в :ref:`финальном статусе<status_list>`.
| 3. Повторный платёж – необходимо вызвать новую транзакцию оплаты с использованием ссылочного идентификатора, полученного на предыдущем шаге.

Сценарий повторной предавторизации
--------------------------------------------------

.. uml::
  :align: center

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 1
  skinparam maxmessagesize 1200
  skinparam sequenceParticipant underline
  actor Плательщик
  participant "Присоединяющаяся Сторона" as A
  participant "Платёжный Шлюз" as B
  autonumber
  hnote over Плательщик,B : Инициация платежа
  == Регистрация карты ==
  A -> B: api/v2/create-card-ref/
  activate B
  activate A
  B --> A: Возврат ИД токена карты
  deactivate B
  A -> A: Сохранение ИД токена карты \nв профиле Плательщика
  deactivate A
  == Получение информации карты ==
  group Опционально
  A -> B: api/v2/get-card-info/
  activate A
  activate B
  B --> A: Возврат информации карты
  deactivate A
  deactivate B
  end
  == Повторяющаяся Преавторизация ==
  group Опционально
  Плательщик -> A: Инициация Повторяющейся Преавторизации
  activate A
  activate Плательщик
  end
  A -> A: Получение ИД токена карты \nиз профиля Плательщика
  group Опционально
  A -> Плательщик: Запрос CVV Плательщика
  Плательщик --> A: Ввод CVV
  end
  A -> B: api/v2/make-rebill-preauth/
  activate B
  B --> A: Ответ ИД транзакции
  hnote over Плательщик,B : См. Схема прохождения 3DS
  group Получение финального статуса
  == Получение обратного вызова ==
  A <- B: Обратный вызов с финальным статусом
  A --> B: HTTP 200
  deactivate B
  == Запрос статуса ==
  A -> B: Получение статуса по ИД транзакции
  activate B
  B --> A: Конечный статус
  deactivate B
  end
  group Опционально
  A --> Плательщик: Показ результата
  deactivate Плательщик
  deactivate A
  end

.. note:: Тип транзакции и имплементация первого платежа зависит от бизнес-модели Присоединяющейся Стороны. Свяжитесь с отделом поддержки Payneteasy для получения подходящего интеграционного сценария для проведения первого платежа.

| (1) Для регистрации карты и получения ссылочного идентификатора см. :ref:`/api/v2/create-card-ref/<api-v2-card-ref-id>`.
| (4) Для выполнения запроса на получение информации по ссылочному идентификатору см. :ref:`/api/v2/get-card-info/</api/v2/get-card-info/>`. Содержимое ответа на этот запрос может быть использовано для показа Плательщику деталей предыдущего использованного метода оплаты или обновления базы данных Присоединяющейся Стороны. Запрос может быть выполнен в любой момент, если у Присоединяющейся стороны уже есть ссылочный идентификатор (Card reference ID).
| (6) Повторная предавторизация может быть инициирована Плательщиком или Присоединяющейся Стороной в соответствии с бизнес-моделью.
| (8, 9) Присоединяющаяся Сторона отправляет запрос Плательщику для ввода CVV/CVC (если применимо для сценария повторной.предавторизации)
| (10) Для инициирования транзакции рекуррентной преавторизации см. :ref:`/api/v2/make-rebill-preauth/</api/v2/make-rebill-preauth/>`. По умолчанию 3DS инициируется и выполняется платежным шлюзом через :ref:`Упрощенную схему аутентификации<simplified_authentication_flow>`. См. :ref:`Схему принятия решения по 3DS<3ds_2x_decision_making_schema_preauth>`.
| (12) Для имплементации обратного вызова с обработкой финального статуса см. :ref:`Обратный вызов Присоединяющейся Стороны<merchant_callbacks>`.
| (14) Для имплементации запроса статуса, см. :ref:`/api/v2/status/</api/v2/status/>`. Статус должен запрашиваться несколько раз с интервалами в 3-5 секунд до получения финального статуса в ответе.
| (16) Результаты транзакции могут отправляться Присоединяющейся Стороной в соответствии с бизнес-моделью или по запросу Плательщика. 

.. _3ds_2x_decision_making_schema_preauth:

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

.. uml::
  :align: center

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

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

| (1) Для реализации запроса статуса заказа см. :ref:`/api/v2/status/</api/v2/status/>`. Статус следует запрашивать несколько раз с интервалом 3-5 секунд до получения финального статуса в ответе.
| (4) Если значения html и redirect-to, см. :ref:`Упрощённый сценарий аутентификации с html страницей<simplified_authentication_flow>`.
| (5) То же, что и пункт (1).

.. note:: «:ref:`Схема принятия решения по 3DS<3ds_2x_decision_making_schema_preauth>` демонстрирует процесс инициирования и выполнения 3DS платежным шлюзом. Для ознакомления с другими сценариями реализации 3DS, пожалуйста, изучите :ref:`Обзор 3DS<3ds_implementation_scenarios>` и свяжитесь с менеджером поддержки». 


.. _Non3D_Sale:

Сценарий без 3DS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Оплата считается проведённой без прохождения 3DS (без 3DS аутентификации) при нижеприведённых условиях:

| 1. Соблюдены шаги 1-2-(5)-6 :ref:`Схемы Прохождения 3DS<3ds_server_to_server_sale_reference>`.
| 2. Отсутствие параметров :code:`tds_status`, :code:`html` и :code:`redirect-to`.
| 3. Транзакция получила финальный статус (подтверждено, отклонено, ошибка, отфильтровано).

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

.. _simplified_authentication_flow:

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

.. 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.
  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** to analyze status response;
  end fork
  stop
  legend left
  =Legend
  | Color | Implementation responsibility |
  |<#Turquoise>| Connecting party |
  | | Other Party |
  endlegend

| (1) и (2). Для имплементации запроса статуса заказа, см. :ref:`/api/v2/status/</api/v2/status/>`.
| (9) Для инициации финального перенаправления см. :ref:`Финальное перенаправление<final_redirect>`.
| (10) HTML-страница ожидания в контуре Присоединяющейся Стороны может иметь произвольный дизайн и должна взаимодействовать с сервером Присоединяющейся Стороны в соответствии с диаграммой.
| (15) и (16) то же, что и (1) и (2).



.. _capture_preauth:

Сценарий списания
---------------------------------------------------------

.. uml::
  :align: center

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 1
  skinparam maxmessagesize 100
  skinparam sequenceParticipant underline
  actor Плательщик
  participant "Присоединяющаяся Сторона" as A
  participant "Платёжный Шлюз" as B
  hnote over Плательщик,B : Успешная транзакция преавторизации
  autonumber
  == Списание ==
  group Опционально
  Плательщик -> A: Инициация списания
  activate Плательщик
  activate A
  end
  A -> B: api/v2/capture
  activate B
  B --> A: ИД транзакции
  B -> B: Обработка списания
  group Получение финального статуса
  == Получение обратного вызова ==
  A <- B: Обратный вызов с финальным статусом
  A --> B: HTTP 200
  deactivate B
  == Запрос статуса ==
  A -> B: Получение статуса по ИД транзакции api/v2/status
  activate B
  B --> A: Ответ со статусом, Order-stage
  deactivate B
  end
  group Опционально
  A --> Плательщик: Конечный статус
  deactivate Плательщик
  deactivate A
  end


| (1) Списание может быть инициировано Присоединяющейся Стороной в соответствии с бизнес-моделью или по запросу Плательщика.
| (2) Для имплементации запроса на списание см. :ref:`/api/v2/capture/</api/v2/capture/>`.
| (5) Обратный вызов по списанию будет отправлен только в случае, если :ex:`notify_url` был предоставлен в инициирующем запросе предавторизации или дополнительный обратный вызов установлен на предоставленный URL для списаний на уровне терминала. Если в запросе предавторизации был предоставлен :ex:`server_callback_url`, обратный вызов по списанию не будет отправлен. Для обработки обратных вызовов см. :ref:`Обратный вызов Присоединяющейся Стороны<merchant_callbacks>`.
| (7) Для реализации запроса статуса заказа см. :ref:`/api/v2/status/</api/v2/status/>`. Статус следует запрашивать несколько раз с интервалом 3-5 секунд, пока в ответе не будет получен финальный статус.
| (9) Конечный статус может быть предоставлен Присоединяющейся Стороной в соответствии с бизнес-моделью или по запросу Плательщика.

.. _cancel_preauth:

Сценарий отмены
-----------------------------------------------------

.. uml::
  :align: center

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 1
  skinparam maxmessagesize 100
  skinparam sequenceParticipant underline
  actor Плательщик
  participant "Присоединяющаяся Сторона" as A
  participant "Платёжный Шлюз" as B
  hnote over Плательщик,B : Успешная транзакция преавторизации
  autonumber
  == Отмена ==
  group Опционально
  Плательщик -> A: Инициация отмены
  activate Плательщик
  activate A
  end
  A -> B: api/v2/return
  activate B
  B --> A: ИД транзакции
  B -> B: Обработка отмены
  group Получение финального статуса
  == Получение обратного вызова ==
  A <- B: Обратный вызов с финальным статусом
  A --> B: HTTP 200
  deactivate B
  == Запрос статуса ==
  A -> B: Получение статуса по ИД транзакции api/v2/status
  activate B
  B --> A: Ответ со статусом, Order-stage
  deactivate B
  end
  group Опционально
  A --> Плательщик: Конечный статус
  deactivate Плательщик
  deactivate A
  end

| (1) Отмена предавторизации может быть вызвана Присоединяющейся Стороной в соответствии с бизнес-моделью или по запросу Плательщика.
| (2) Для имплементации запроса на отмену см. :ref:`/api/v2/return/</api/v2/return/>`.
| (5) Обратный вызов по отмене будет отправлен только в случае, если :ex:`notify_url` был предоставлен в инициирующем запросе предавторизации или дополнительный обратный вызов установлен на предоставленный URL для отмен на уровне терминала. Если в запросе предавторизации был предоставлен :ex:`server_callback_url`, обратный вызов по отмене не будет отправлен. Для обработки обратных вызовов см. :ref:`Обратный вызов Присоединяющейся Стороны<merchant_callbacks>`.
| (7) Для реализации запроса статуса заказа см. :ref:`/api/v2/status/</api/v2/status/>`. Статус следует запрашивать несколько раз с интервалом 3-5 секунд, пока в ответе не будет получен финальный статус.
| (9) Конечный статус может быть предоставлен Присоединяющейся Стороной в соответствии с бизнес-моделью или по запросу Плательщика.

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

   ----

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

      `Subscription and recurring billing for retail businesses → <https://payneteasy.com/branches/retail>`_

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

   ----

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

      `Подписочные и рекуррентные платежи для ритейла → <https://payneteasy.ru/branches/retail>`_