.. meta::
   :description: Интеграция Payment Cashier (параллельная форма) с Payneteasy: размещённая форма, которая показывает Плательщику несколько способов оплаты в зависимости от страны и валюты.

.. _parallel_form:

Payment Cashier
###############


.. role:: ex

.. role:: code

Введение
^^^^^^^^^^^^

| Интеграция с Платёжной кассой позволяет Плательщику выбрать способ оплаты для транзакции. Платёжную кассу можно настроить на стороне Присоединяющейся стороны или на стороне Платёжного Шлюза (также называемой Параллельной формой), что рассматривается в этом примере использования. Присоединяющаяся сторона перенаправляет Плательщика в Параллельную форму, размещённую на стороне Платёжного Шлюза; Плательщик выбирает один из доступных способов оплаты и пытается выполнить платёж. Параллельная форма может инициировать транзакции :ex:`sale` или :ex:`preauth` для каждого настроенного способа оплаты. После успешной транзакции Плательщик перенаправляется обратно к Присоединяющейся стороне. Подробнее см. :ref:`Настройка платёжного потока<payment_flow_customization_url>`.
| Чтобы узнать, как можно настраивать формы, перейдите к разделу :ref:`Настройка форм<forms_customization_reference>` с примерами и макросами :ref:`Настройки страницы Платёжной кассы<payment_cashier_page_customization_reference>`, :ref:`Настройки страницы оплаты<payment_page_customization_reference>`, :ref:`Предварительно заполненные данные держателя карты на странице оплаты<prefilled_cardholder_data_in_payment_page>`, :ref:`Настройки страницы ожидания<wait_page_customization_reference>` и :ref:`Настройки страницы завершения<finish_page_customization_reference>`.
|
| Значение терминов см. в :ref:`Глоссарии<glossary>`.
|
| Платёжная касса, настроенная в Платёжном Шлюзе, имеет внутреннюю структуру Главных Эндпоинтов, объединяющих обычные Эндпоинты. Обычные Эндпоинты, подключённые к Главному Эндпоинту, называются Вспомогательными Эндпоинтами. Каждый Вспомогательный Эндпоинт настраивается для конкретного способа оплаты. При выполнении оплаты Плательщик может выбрать способ оплаты в Параллельной форме. Когда Плательщик выбирает способ оплаты, Параллельная форма инициирует вспомогательную транзакцию в соответствующем Вспомогательном Эндпоинте. Если валюта Вспомогательного Эндпоинта отличается от валюты Главного Эндпоинта, сумма главной транзакции будет конвертирована в соответствующую валюту этого способа оплаты. Кроме того, Главные Эндпоинты можно объединить в Группу Эндпоинтов для создания единой логической сущности для мультивалютных интеграций. См. :ref:`Параметры мультивалютной интеграции<cashier_multicurrency>` и выберите предпочтительный вариант с менеджером службы поддержки Payneteasy.

Payment Cashier Flow
^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

    skinparam roundcorner 20
    skinparam sequenceArrowThickness 2
    skinparam ParticipantPadding 30
    actor Плательщик as Customer
    participant "Веб-сайт\nПрисоединяющейся Стороны" as Merchant
    participant "Платёжный Шлюз" as g
    autonumber
    Customer -> Merchant: Инициализия
    activate Merchant
    == Запрос кассы ==
    Merchant -> g: api/v2/sale-form
    activate g
    g --> Merchant: Redirect-url, orderId
    deactivate g
    Merchant -> Customer: Предоставление redirect-url \nбраузеру Плательщика
    deactivate Merchant
    activate Customer
    Customer -> g: GET redirect-url
    deactivate Customer
    activate g
    g --> Customer: Возврат параллельной формы
    deactivate g
    activate Customer
    Customer --> Customer: Выбор Плательщиком метода оплаты
    activate Customer
    Customer -> g: Запрос параллельной формой транзакции \nдля выбранного метода оплаты
    deactivate Customer
    activate g
    g --> g: Инициирование \nвспомогательной транзакции \nдля выбранного метода оплаты
    g --> Customer: Возврат вспомогательной формы
    deactivate g
    alt if Открытие Плательщиком другой \nпараллельной формы окна оплаты
    Customer --> Customer: Выбор Плательщиком метода оплаты
    activate Customer
    Customer -> g: Запрос параллельной формой транзакции \nдля выбранного метода оплаты
    deactivate Customer
    activate g
    g --> g: Инициирование \nвспомогательной транзакции \nдля выбранного метода оплаты
    g --> Customer: Возврат вспомогательной формы
    deactivate g
    end
    Customer -> g: Подтверждение формы
    deactivate Customer
    activate g
    g --> g: Обработка транзакции
    == Финальное перенаправление Плательщика ==
    g -> Customer: redirect_url веб-сайта \nПрисоединяющейся Стороны
    activate Customer
    Customer -> Merchant: POST redirect_url\nstatus, orderid
    deactivate Customer
    group Получение финального статуса
    == Получение обратного вызова \nПрисоединяющейся Стороны ==
    activate Merchant
    Merchant <- g: Обратный вызов \nс финальным статусом
    g <-- Merchant: HTTP 200
    deactivate g
    == Запрос статуса ==
    Merchant -> g: api/v2/status
    activate g
    g --> Merchant: Ответ \nstatus, order-stage
    deactivate g
    end
    Merchant --> Customer: Показ результата
    deactivate Merchant

| (2) Для реализации запроса sale-form см. :ref:`/api/v2/sale-form/</api/v2/sale-form/>`.
| (14) Для реализации финального перенаправления см. :ref:`Final Redirect<final_redirect>`.
| (16,17) Для реализации запроса статуса заказа см. :ref:`/api/v2/status/</api/v2/status/>`. Статус следует запрашивать несколько раз с интервалами 3–5 секунд, пока в ответе не будет получен окончательный статус.
| (18) Сведения о реализации callback с обработкой финального статуса см. в :ref:`Callbacks Присоединяющейся стороны<merchant_callbacks>`. Callback отправляется со статусом основной транзакции (транзакции кассира). Чтобы получать дополнительные callback о результате каждой инициированной транзакции, обратитесь к менеджеру поддержки Payneteasy.


.. _cashier_multicurrency:

Options For Multi-Currency Integration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Платёжную кассу можно настроить для нескольких валют. Для каждой валюты транзакции, необходимой Присоединяющейся стороне, создаётся отдельный Главный Эндпоинт с уникальным идентификатором. Чтобы в будущем не интегрироваться с новыми идентификаторами Главных Эндпоинтов для поддержки дополнительных валют, Присоединяющаяся сторона может выбрать интеграцию с Группой Эндпоинтов. Группа Эндпоинтов — это единая логическая сущность, объединяющая Главные Эндпоинты в разных валютах. В будущем Главные Эндпоинты в новых валютах можно добавить в ту же Группу Эндпоинтов.

.. uml::
  :align: center

  title Options for multi-currency processing integration
  package "Integration to Endpoint Group" {
    class "layoutHelper1" #ffe6cc;line:black;line.dotted
    class "Payment\nmethod 1\ncurrency A" #ffe6cc;line:black;line.dotted
    class "Payment\nmethod 2\ncurrency A" #ffe6cc;line:black;line.dotted
    class "Payment\nmethod 1\ncurrency B" #dae8fc;line:black;line.dotted
    class "Payment\nmethod 2\ncurrency X" #daf9fc;line:black;line.dotted
    class "Master Endpoint\n currency A" #ffe6cc;line:black;line.dotted
    class "Master Endpoint\n currency B" #dae8fc;line:black;line.dotted
    class "Endpoint\nGroup" #ffcdcc;line:black;line.dotted
  }
  package "Integration to multiple Master Endpoints" {
  class "layoutHelper2\n" #ffe6cc;line:black;line.dotted
    class "Payment\nmethod 1\ncurrency C" #e1d5e7;line:black;line.dotted
    class "Payment\nmethod 2\ncurrency C" #e1d5e7;line:black;line.dotted
    class "Payment\nmethod 1\ncurrency D" #dafcdd;line:black;line.dotted
    class "Payment\nmethod 2\ncurrency Y" #abf8d8;line:black;line.dotted
    class "Master Endpoint\n currency C" #e1d5e7;line:black;line.dotted
    class "Master Endpoint\n currency D" #dafcdd;line:black;line.dotted
  }
  class "layoutHelper3" #ffe6cc;line:black;line.dotted
  class "Connecting Party\n (Merchant)" #ececec;line:black;line.bold

  "Connecting Party\n (Merchant)" -left-> "Endpoint\nGroup"
  "Connecting Party\n (Merchant)" -down-> "layoutHelper3"
  "Connecting Party\n (Merchant)" -down-> "Master Endpoint\n currency C"
  "Connecting Party\n (Merchant)" -down-> "Master Endpoint\n currency D"

  "Endpoint\nGroup" -down- "Master Endpoint\n currency A"
  "Endpoint\nGroup" -down- "Master Endpoint\n currency B"
  "Master Endpoint\n currency C" -down- "Payment\nmethod 1\ncurrency C"
  "Master Endpoint\n currency C" -down- "Payment\nmethod 2\ncurrency C"
  "Master Endpoint\n currency D" -down- "Payment\nmethod 1\ncurrency D"
  "Master Endpoint\n currency D" -down- "Payment\nmethod 2\ncurrency Y"
  "Master Endpoint\n currency A" -down- "Payment\nmethod 1\ncurrency A"
  "Master Endpoint\n currency A" -down- "Payment\nmethod 2\ncurrency A"
  "Master Endpoint\n currency B" -down- "Payment\nmethod 1\ncurrency B"
  "Master Endpoint\n currency B" -down- "Payment\nmethod 2\ncurrency X"
  "Connecting Party\n (Merchant)" -left[hidden]- "layoutHelper1"
  "Connecting Party\n (Merchant)" -right[hidden]- "layoutHelper2\n"
  "layoutHelper1" -[hidden]- "Master Endpoint\n currency A"
  "layoutHelper1" -[hidden]- "Master Endpoint\n currency B"
  "layoutHelper2\n" -[hidden]- "Master Endpoint\n currency C"
  "layoutHelper2\n" -[hidden]- "Master Endpoint\n currency D"
  hide members
  hide circle
  hide layoutHelper1
  hide layoutHelper2\n
  hide layoutHelper3

.. _payment_flow_customization_url:

Payment Flow Customization Scenarios
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Callback Notification Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

| По умолчанию обратные вызовы имеют следующую форму:
|
| Обратный вызов главной конечной точки: client_orderid=A&orderid=B
| Обратный вызов вспомогательной конечной точки: client_orderid=A&orderid=C (если он установлен на вспомогательной конечной точке)
|
| Для корректной обработки обратных вызовов на стороне Присоединяющейся стороны важно учитывать, что обратный вызов от вспомогательной конечной точки может прийти раньше, чем от главной конечной точки: окончательный статус вспомогательной транзакции запускает окончательный статус главной транзакции.
|
| Существует другая настройка, которая может быть предпочтительнее стандартной (чтобы включить эту функцию, пожалуйста, обратитесь к менеджеру поддержки Payneteasy) :
|
| Обратный вызов главной конечной точки: client_orderid=A&orderid=B
| Обратный вызов вспомогательной конечной точки: client_orderid=B&orderid=C (если он установлен на вспомогательной конечной точке)
|
| Обратный вызов на вспомогательной конечной точке может потребоваться в двух случаях:
|
| 1. Присоединяющаяся сторона хочет иметь полную информацию обо всех попытках оплаты в Payment Cashier.
| 2. Присоединяющаяся сторона реализует интеграцию :ex:`preauth` -> :ex:`capture`/:ex:`cancel` в Payment Cashier. Транзакции :ex:`Capture`/:ex:`cancel` могут инициироваться для одобренной транзакции :ex:`preauth` запросом к Master Endpoint ID с использованием :code:`orderid` вспомогательной транзакции. Этот :code:`orderid` поступает в callback от Auxiliary Endpoint, когда транзакция :ex:`preauth` получает окончательный статус.

Redirect Payer After Any Decline
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, the Payer stays on the Parallel Form if one of the auxiliary transactions is declined, so the Payer can try to pay with another available payment method.
There is an option to redirect the Payer to the Connecting Party's website after receiving an unsuccessful status (:ex:`decline`, :ex:`filtered`, :ex:`error`, etc.) on any payment method tab of the Cashier (auxiliary transaction decline will cause the decline on the master transaction). Please contact Payneteasy support manager to enable this feature.

Keep Payer on Finish Page
~~~~~~~~~~~~~~~~~~~~~~~~~

When one of the auxiliary transactions is approved, Parallel Form redirects the Payer back to the Connecting Party's website (see :ref:`Final Redirect<final_redirect>`).
There is an option to keep the Payer on Finish Page instead of redirecting for approved auxiliary transaction (it might be useful if Payment Cashier is displayed in an iframe on the Connecting Party's website). Please contact Payneteasy support manager to enable this feature.

Forced Payer Redirect
~~~~~~~~~~~~~~~~~~~~~

Если необходимо перенаправить Плательщика на страницу завершения, пока транзакция остаётся в обработке, в указанные ниже формы необходимо добавить следующий код:

Option 1
--------

Auxiliary Finish Form Template:

.. highlight:: html

::

    <script>
            function backToMerchant() {
                window.parent.postMessage(
                    "redirect-to-merchant",
                    "https://pay.connectingparty.com"
                );
            }
        </script>
    </head>
    <body onload="backToMerchant()">
    <div class="container">
        <div class="main">
            <h2 class="summary__title">Deposit <span class="status-title">${STATUS}</span></h2>
            <div class="back">
                <a class="link" href="#" onclick="backToMerchant()">Back to merchant website</a>
            </div>
        </div>
    </div>

Master Payment Form Template:

.. highlight:: html

::

    <script>
        window.addEventListener("message", function(event) {
            if (event.origin !== "https://pay.connectingparty.com")
                return;
            if (event.data === "redirect-to-merchant") {
                window.location.replace("https://connectingparty.com/result");
            }
        }, false);
    </script>

Option 2
--------

Auxiliary Finish Form Template:

.. highlight:: html

::

    <div class="container">
        <div class="main">
            <h2 class="summary__title">Deposit <span class="status-title">${STATUS}</span></h2>
            <div class="back">
                <a class="link" target="_parent" href="${CUSTOMER_REDIRECT_URL}">Back to merchant website</a>
            </div>
        </div>
    </div>

Subsequent Transactions on Payment Cashier
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Если Присоединяющаяся сторона хочет инициировать транзакции :ex:`cancel`, :ex:`reversal` или :ex:`capture` в Платёжной кассе, ей необходимо отправить запрос на идентификатор Главного Эндпоинта, используя :code:`order_id` вспомогательной транзакции. Это значение можно получить в callback от Вспомогательного Эндпоинта вместе с другими сведениями об этой транзакции. Подробнее см. в разделе :ref:`Параметры уведомления callback<payment_flow_customization_url>` и ознакомьтесь с приведённым ниже потоком транзакции.

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

.. uml::
  :align: center

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

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

.. uml::
  :align: center

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

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

Reversal Flow
~~~~~~~~~~~~~

.. uml::
  :align: center

    skinparam roundcorner 20
    skinparam sequenceArrowThickness 1
    skinparam maxmessagesize 100
    skinparam sequenceParticipant underline
    actor Плательщик
    participant "Присоединяющаяся Сторона" as A
    participant "Платёжный Шлюз" as B
    hnote over A,B : Успешная транзакция платежа или списания
    autonumber
    group Опционально
    Плательщик -> A: Инициация возврата
    activate A
    end
    == Возврат ==
    A -> B: api/v2/return
    activate B
    B --> A: ИД транзакции
    B -> B: Обработка возврата
    group Получение финального статуса
    == Получение обратного вызова \nПрисоединяющейся Стороны ==
    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 A
    end

| Возврат может быть инициирован Присоединяющейся Стороной, опираясь на внутреннюю политику компании или по запросу Плательщика.
| (2) Для имплементации запроса возврата см. :ref:`/api/v2/return/</api/v2/return/>`. 
| (5) Callback для Return будет отправлен только если :code:`notify_url` был предоставлен в первоначальном запросе транзакции или дополнительный URL callback для транзакций Return указан на уровне endpoint. Если :code:`server_callback_url` был предоставлен в первоначальном запросе транзакции, callback для Return не отправляется. Для реализации callback с обработкой окончательного статуса см. :ref:`Connecting Party Callbacks<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

      `Fintegrate Payment Cashier System overview → <https://payneteasy.com/solutions/fintegrate-payment-cashier-system>`_

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

   ----

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

      `Fintegrate — оркестратор платежей → <https://payneteasy.ru/solutions/fintegrate>`_