.. _bank_transfer_with_invoice:

Bank transfer with Invoice
##########################

.. toctree::
   :maxdepth: 3

.. contents::
   :local:

.. role:: ex

.. role:: code

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

| This Use-Case describes how Connecting Party can issue invoices for Swift or similar wire bank transfer systems in Payment Gateway and display these invoices to Payers. Incoming bank transfer statuses might be updated automatically or manually.
|
| See terms definitions in :ref:`Glossary<glossary>`.

Bank Wire Transfer 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
    == Purchase payment request ==
    Merchant -> g: api/v2/auth-cash
    activate g
    g --> Merchant: orderId
    g --> g: Generating payment invoice
    == Receive Connecting Party Callback ==
    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, receipt-id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    deactivate g
    == Get invoice in XML, PDF or both ==
    group XML
    g <-- Merchant: view-invoice-xml/ENDPOINTID/receipt-id
    activate g
    g --> Merchant: XML
    deactivate g
    end
    group PDF
    g <-- Merchant: view-invoice/ENDPOINTID/receipt-id
    activate g
    g --> Merchant: PDF
    deactivate g
    end
    Merchant -> Customer: Show result
    deactivate Merchant

| (2) To implement bank transfer request see :ref:`/api/v2/auth-cash/</api/v2/auth-cash/>`.
| (5,6) 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. :ex:`receipt-id` will be received in status response.
| (7) To implement callback with final status handling see :ref:`Connecting Party<merchant_callbacks>`.
| (9) To implement view-invoice-xml request see :ref:`/view-invoice-xml/</view-invoice-xml/>`. :ex:`receipt-id` will be used to get invoice in XML format.
| (11) To implement view-invoice request see :ref:`/view-invoice/</view-invoice/>`. :ex:`receipt-id` will be used to get invoice in PDF format.

Simple Bank Transfer Flow Statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 50, 50
   :header-rows: 1
   :class: longtable

   * - Stage name
     - Description
   * - :code:`AUTH_APPROVED`
     - Invoice was issued for the Payer.
   * - :code:`CANCEL_APPROVED`
     - Payer didn't complete the transfer. This stage is optional and may be used for better transaction control in back-office.
   * - :code:`CAPTURE_APPROVED`
     - Funds were transferred to the Connecting Party account (settled).
   * - :code:`VOID_APPROVED`
     - Funds were returned by the Payer (recalled).
   * - :code:`REVERSAL_APPROVED`
     - Funds were returned to the Payer by Connecting Party.

Extended Bank Transfer Flow Statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 50, 50
   :header-rows: 1
   :class: longtable

   * - Stage name
     - Description
   * - :code:`AUTH_STARTING`
     - Transaction was initiated.
   * - :code:`AUTH_INVOICED`
     - Invoice was issued for the Payer. It may be downloaded in back-office, sent to Payer by e-mail or requested via API.
   * - :code:`AUTH_SENT`
     - Payer informed the Connecting Party that invoice have been paid. This stage may be skipped.
   * - :code:`CANCEL_APPROVED`
     - Payer didn't complete the transfer. This stage is optional and may be used for better transaction control in back-office.
   * - :code:`AUTH_APPROVED`
     - Transfer was received by the bank.
   * - :code:`CAPTURE_APPROVED`
     - Funds were transferred to the Connecting Party account (settled).
   * - :code:`VOID_APPROVED`
     - Funds were returned by the Payer (recalled).
   * - :code:`REVERSAL_APPROVED`
     - Funds were returned to the Payer by Connecting Party.
   * - :code:`CHARGEBACK_APPROVED`
     - Funds were charged back by the Payer.