.. _payout_by_ref:

Payout By Reference
#######################################

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

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

| Payout-by-ref is a type of transaction which results in funds transfer from Connecting Party banking account to customer (receiver) bank card, banking account or digital wallet. Payout transaction in most cases is used for bank account funding.
| Receiver account Card Reference ID (:ex:`destination-card-ref-id`) for Payout By Reference can be obtained on Card registration step, see :ex:`card-ref-id` in :ref:`v2/create-card-ref<api-v2-card-ref-id>` or :ref:`v4/create-card-ref<api-v4-card-ref-id>`.
| Card registration requires a previously made transaction in final status, so Payout-by-ref can be initiated only for already registered Receivers.

| See terms definitions in :ref:`Glossary<glossary>`.

Payout Flow
^^^^^^^^^^^^^^^^^^^^^^

.. uml::
  :align: center

  @startuml
  participant Receiver as R
  participant "Connecting Party" as cp
  autonumber
  group Optional
  R -> cp : Checkout
  activate cp
  end
  == Payout request ==
  cp -> "Payneteasy": /api/v4/payout-by-ref/
  activate "Payneteasy"
  "Payneteasy" --> cp: Order ID
  deactivate cp
  == Receive Connecting Party Callback ==
  "Payneteasy" --> "Payneteasy": Processing\nPayout
  group Get Final Status
  cp <- "Payneteasy" : Callback with Final Status
  "Payneteasy" <-- cp: HTTP 200
  deactivate "Payneteasy"
  == Order Status request ==
  cp -> "Payneteasy": Get status by Order ID\napi/v2/status
  activate "Payneteasy"
  "Payneteasy" --> cp : Response\nstatus,order-stage
  deactivate "Payneteasy"
  end
  group Optional
  cp --> R: Show result
  deactivate cp
  end
  @enduml

| (1) Payout-by-ref can be initiated by Connecting Party based on internal business model or Receiver’s request.
| (2) To implement payout-by-ref transaction see :ref:`/api/v4/payout-by-ref/`.
| (5) 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.
| (7) To implement callback with final status handling see :ref:`Connecting Party Callback<merchant_callbacks>`.
| (9) Final Status can be sent by Connecting Party based on internal business model or by Receiver’s request.