.. _return_transactions:

Return Transactions
######################################

.. toctree::
   :maxdepth: 3

.. contents::
    :local:

.. role:: ex

.. role:: code

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

| **Return:** Return transaction means returning money back to a Payer's credit card or other type of account. Returned funds are not instantly displayed on Payer's banking account, refund processing by Acquirer can take several days after it has been initiated. Return can only be processed for :ex:`Sale`, :ex:`Preauth` and :ex:`Capture` transactions in the final successful status. For :ex:`Preauth` it makes :ex:`Cancel` transaction, for :ex:`Capture` and :ex:`Sale` – :ex:`Reversal`. See :ref:`statuses`.
| **Void:** Void transaction sometimes can be used instead of Refund transaction to return money back to Payer’s account. Void request excludes transaction from Acquirer’s clearing list. The transaction can only be voided if it has been authorized but not settled yet. If clearing already happened or Void is not supported, it’s only possible to return funds to Payer’s account with Refund transaction.
| Void can only be processed for :ex:`Sale` and :ex:`Capture` transactions in the final successful status, Void request makes :ex:`Void` transaction. See :ref:`statuses`. Void might not be supported in most cases, ask support manager for details.
|
| See terms definitions in :ref:`Glossary<glossary>`.

.. _return_request_url:

Return Transaction 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, Preauth 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 :ex:`notify_url` was provided in initial transaction request or additional callback URL for Return transactions is specified on the endpoint level. If :ex:`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.

.. _void_request_url:

Void Transaction 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 Void
    activate A
    end
    == Void ==
    A -> B: api/v2/void
    activate B
    B --> A: Order ID
    B -> B: Process Void
    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 A
    end

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