.. _parallel_form:

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

.. toctree::
   :maxdepth: 3

.. contents::
    :local:

.. role:: ex

.. role:: code

Introduction
^^^^^^^^^^^^

| Payment Cashier integration allows Payer to choose the payment method for transaction. Payment Cashier can be configured on the Connecting Party side or the Payment Gateway (it is also referred to as Parallel Form) side which is covered in this Use-Case. Connecting Party redirects the Payer to Parallel Form hosted on the Payment Gateway side, the Payer selects one of the available payment methods and tries to perform the payment. Parallel Form can initiate :ex:`sale` or :ex:`preauth` transactions for each configured payment method. Once the transaction is successful, the Payer gets redirected back to the Connecting Party. For more information please see :ref:`Payment Flow Customization<payment_flow_customization_url>`.
| To see how the forms can be customized, please follow the :ref:`Forms Customization<forms_customization_reference>` reference to see examples and macros of :ref:`Payment Cashier Page Customization<payment_cashier_page_customization_reference>`, :ref:`Payment Page Customization<payment_page_customization_reference>`, :ref:`Prefilled Cardholder Data in Payment Page<prefilled_cardholder_data_in_payment_page>`, :ref:`Wait Page Customization<wait_page_customization_reference>`, and :ref:`Finish Page Customization<finish_page_customization_reference>`.
|
| See terms definitions in :ref:`Glossary<glossary>`.
|
| Payment Cashier configured in the Payment Gateway has internal structure of Master Endpoints that combine regular Endpoints. Regular Endpoints connected to the Master Endpoint are called Auxiliary Endpoints. Each Auxiliary Endpoint is configured for specific payment method. When making a payment, the Payer can choose the payment method on the Parallel Form. When Payer selects the payment method, Parallel Form initiates an auxiliary transaction on the corresponding Auxiliary Endpoint. If Auxiliary Endpoint currency is different from Master Endpoint currency, the master transaction amount will be converted to respective currency of this payment method. Additionally, Master Endpoints can be consolidated in the Endpoint Group to create single logical unit for multi-currency integrations. See the :ref:`Options for multi-currency integration<cashier_multicurrency>` and select the preferred option with Payneteasy support manager.

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

.. uml::
  :align: center

    skinparam roundcorner 20
    skinparam sequenceArrowThickness 2
    skinparam ParticipantPadding 30
    actor Payer as Customer
    participant "Connecting Party\nwebsite" as Merchant
    participant "Payment Gateway" as g
    autonumber
    Customer -> Merchant: Checkout
    activate Merchant
    == Payment cashier request ==
    Merchant -> g: api/v2/sale-form
    activate g
    g --> Merchant: Redirect-url, orderId
    deactivate g
    Merchant -> Customer: Provide redirect-url \nto Payer’s browser
    deactivate Merchant
    activate Customer
    Customer -> g: GET redirect-url
    deactivate Customer
    activate g
    g --> Customer: Return parallel form
    deactivate g
    activate Customer
    Customer --> Customer: Payer selects payment method
    activate Customer
    Customer -> g: Parallel form requests selected payment method transaction
    deactivate Customer
    activate g
    g --> g: Initiate auxiliary transaction for \nselected payment method
    g --> Customer: Return auxiliary form
    deactivate g
    alt if Payer opens another parallel form  payment tab
    Customer --> Customer: Payer selects payment method
    activate Customer
    Customer -> g: Parallel form requests selected payment method transaction
    deactivate Customer
    activate g
    g --> g: Initiate auxiliary transaction for \nselected payment method
    g --> Customer: Return another auxiliary form
    deactivate g
    end
    Customer -> g: Submit form
    deactivate Customer
    activate g
    g --> g: Process payment
    == Final redirect of Payer ==
    g -> Customer: Connecting Party website redirect_url
    activate Customer
    Customer -> Merchant: POST redirect_url\nstatus, orderid
    deactivate Customer
    group Get Final Status
    == Receive Connecting Party Callback ==
    activate Merchant
    Merchant <- g: Сallback with final status
    g <-- Merchant: HTTP 200
    deactivate g
    == Order Status Request ==
    Merchant -> g: api/v2/status
    activate g
    g --> Merchant: Response \nstatus, order-stage
    deactivate g
    end
    Merchant --> Customer: Show result
    deactivate Merchant

| (2) To implement a sale-form request see :ref:`/api/v2/sale-form/</api/v2/sale-form/>`.
| (14) To implement the final redirect see :ref:`Final Redirect<final_redirect>`.
| (16,17) To implement an order status request see :ref:`/api/v2/status/</api/v2/status/>`. Status should be requested multiple times with 3-5-second intervals until final status will be received in response.
| (18) To implement callback with final status handling see :ref:`Connecting Party Callbacks<merchant_callbacks>`. Callback is sent with the status of the master transaction (cashier transactions). To get additional callbacks about the result of each initiated transactions, please contact Payneteasy support manager.


.. _cashier_multicurrency:

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

Payment Cashier can be configured for multiple currencies. For each transaction currency required by Connecting Party, a separate Master Endpoint with unique ID is created. In order to avoid integration to new Master Endpoint IDs for additional currencies support in future, Connecting Party can choose integration to Endpoint Group instead. Endpoint Group is a single logical unit which consolidates Master Endpoints in different currencies. Master Endpoints in new currencies can be added to the same Endpoint Group in future.

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

| By default, callbacks have the following form:
|
| Master Endpoint Callback: client_orderid=A&orderid=B
| Auxiliary Endpoint Callback: client_orderid=A&orderid=C (if it is set on an Auxiliary Endpoint)
|
| For correct callback handling on Connecting Party side it is important to note that the callback from the Auxiliary Endpoint may come earlier than the callback from the Master Endpoint (because final status on auxiliary transaction triggers final status on master transaction).
|
| There is another setup that can be preferred over the default one (to enable this feature please contact Payneteasy support manager) :
|
| Master Endpoint Callback: client_orderid=A&orderid=B
| Auxiliary Endpoint Callback: client_orderid=B&orderid=C (if it is set on an Auxiliary Endpoint)
|
| A callback on the Auxiliary Endpoint may be required in two cases:
|
| 1. The Connecting Party wants to have complete information about all payment attempts on the Payment Cashier.
| 2. The Connecting Party implements :ex:`preauth` -> :ex:`capture`/:ex:`cancel` integration on the Payment Cashier. :ex:`Capture`/:ex:`cancel` transactions can be initiated for approved :ex:`preauth` transaction with request sent to Master Endpoint ID by using :code:`orderid` of the auxiliary transaction. This :code:`orderid` comes in a callback from an Auxiliary Endpoint when :ex:`preauth` transaction receives the final status.

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
~~~~~~~~~~~~~~~~~~~~~

If it is necessary to redirect the Payer to the Finish Page while transaction remains in process, the following code must be added to the forms mentioned below:

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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If the Connecting Party wants to initiate :ex:`cancel`, :ex:`reversal` or :ex:`capture` transactions on Payment Cashier, then Connecting Party needs to send a request to the Master Endpoint ID by using an auxiliary transaction's :code:`order_id`. This value can be received in callback from Auxiliary Endpoint together with other details about this transaction. See :ref:`Callback Notification Options<payment_flow_customization_url>` for details and check the transaction flow below.

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 A,B : Successful Preauth Transaction
    autonumber
    group Optional
    Payer -> A: Initiate Cancel
    activate A
    end
    == Cancel ==
    A -> B: api/v2/return
    activate B
    B --> A: Order ID
    B -> B: Process Cancel
    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 api/v2/status
    activate B
    B --> A: Response with Status, Order-stage
    deactivate B
    end
    group Optional
    A --> Payer: Final Status
    deactivate A
    end

| (1) Cancel can be initiated by Connecting Party based on internal business model 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 Callbacks<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.

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 A,B : Successful Preauth Transaction
    autonumber
    group Optional
    Payer -> A: Initiate Capture
    activate A
    end
    == Capture ==
    A -> B: api/v2/capture
    activate B
    B --> A: Order ID
    B -> B: Process Capture
    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 api/v2/status
    activate B
    B --> A: Response with Status, Order-stage
    deactivate B
    end
    group Optional
    A --> Payer: Final Status
    deactivate A
    end

| (1) Capture can be initiated by Connecting Party based on internal business model 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 :code:`notify_url` was provided in initial transaction request or additional callback URL for Capture transactions is specified on the endpoint level. If :code:`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 Callbacks<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.

Reversal 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 A,B : Successful Sale or Capture transaction
    autonumber
    group Optional
    Payer -> A: Initiate Return
    activate A
    end
    == Return ==
    A -> B: api/v2/return
    activate B
    B --> A: Order ID
    B -> B: Process Return
    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 api/v2/status
    activate B
    B --> A: Response with Status, Order-stage
    deactivate B
    end
    group Optional
    A --> Payer: Final Status
    deactivate A
    end

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