.. _api_transfer_status:

Transfer status
###############

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

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

| Transfer status is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_url_transfer_status>` and the :ref:`parameters<api_parameters_transfer_status>`.
| Funds transfer status request is made by Connecting Party’s app to Payneteasy to get the status of transfer transaction.
| It is recommended to send Transfer status request for a period of 2-3 minutes with interval of 3-5 seconds between requests. Connecting Party's server should rely on the callback for final status.

.. _api_url_transfer_status:

API URLs
^^^^^^^^

.. note::
    | The path in API URL should not be hardcoded, as it may be changed in future.

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

   * - Integration
     - Production
   * - :ex:`https://sandbox.payneteasy.com/paynet/dapi/v1/transfer/{endpointId}/{invoiceId}/status`
     - :ex:`https://gate.payneteasy.com/paynet/dapi/v1/transfer/{endpointId}/{invoiceId}/status`

.. _api_parameters_transfer_status:

Request Parameters
^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 30, 45, 25
   :header-rows: 1
   :class: longtable

   * - Parameter Name
     - Description
     - Value
   * - :code:`session`
     -
     - | ``Type``: **Object**
   * - :code:`session.accessToken`
     - The access token key received in Optional consumer authentication.
     - | ``Type``: String
       | ``Length``: 32-128
   * - :code:`session.token`
     - The session token of transfer transaction.
     - | ``Type``: String
       | ``Length``: 16-36

Success Response Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 30, 45, 25
   :header-rows: 1
   :class: longtable

   * - Parameter Name
     - Description
     - Value
   * - :code:`invoiceId`
     - Transfer transaction identifier.
     - | ``Type``: String
   * - :code:`session`
     -
     - | ``Type``: **Object**
   * - :code:`session.token`
     - The session token of transfer transaction.
     - | ``Type``: String
   * - :code:`state`
     - Possible values: ``PROCESSING``, ``REDIRECT_REQUEST``, ``APPROVED``, ``DECLINED``. If Consumer defined transfer rates enable get ``TRANSFER_FEE_REQUEST``.
     - | ``Type``: Enum
   * - :code:`bankOrderId`
     - Required if state is ``APPROVED`` or ``DECLINED``.
     - | ``Necessity``: Conditional
       | ``Type``: String
       | ``Length``: 128
   * - :code:`redirectUrl`
     - Required if state is ``REDIRECT_REQUEST``.
     - | ``Necessity``: Conditional
       | ``Type``: String
       | ``Length``: 128
   * - :code:`orderId`
     - Order identifier in payment processing system.
     - | ``Necessity``: Conditional
       | ``Type``: String
   * - :code:`transaction`
     -
     - | ``Necessity``: Conditional
       | ``Type``: **Object**
   * - :code:`transaction.amountCentis`
     - Amount of money transfered in centis, 1.00 EUR = 100 centis.
     - | ``Necessity``: Conditional
       | ``Type``: Integer
   * - :code:`transaction.commissionCentis`
     - Amount of commission held in centis.
     - | ``Necessity``: Conditional
       | ``Type``: Integer
   * - :code:`transaction.orderCreatedDate`
     - Order creation date in payment processing system.
     - | ``Necessity``: Conditional
       | ``Type``: String
   * - :code:`transaction.transactionCreatedDate`
     - Transaction creation date in payment processing system.
     - | ``Necessity``: Conditional
       | ``Type``: String
   * - :code:`errorCode`
     - Decline reason code, may present if state is ``DECLINED``.
     - | ``Necessity``: Optional
       | ``Type``: Integer
   * - :code:`errorMessage`
     - Decline reason message, may present if state is ``DECLINED``.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 128
   * - :code:`secure3DAuthStatus`
     - Possible values: ``AUTHENTICATED``, ``NOT_AUTHENTICATED``, ``UNSUPPORTED`` means that card does not support 3-D Secure or 3DS authentication process finished with an unknown status.
     - | ``Necessity``: Optional
       | ``Type``: Enum
   * - :code:`randomSumAuthStatus`
     - Possible values: ``AUTHENTICATED``, ``NOT_AUTHENTICATED``.
     - | ``Necessity``: Optional
       | ``Type``: Enum

Success Response Parameters for Consumer defined transfer rates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| Transfer status response includes the :code:`state` parameter with :ex:`TRANSFER_FEE_REQUEST` value and the :code:`transferFeeList` object with a list of commissions for possible processing gates. Each processing gate is represented by it's own aliased name in :code:`assignedId` parameter. :ex:`TRANSFER_FEE_REQUEST` value in :code:`state` parameter exists only in "Consumer defined transfer rates" flow.
| When the transaction reaches :ex:`TRANSFER_FEE_REQUEST` state, the processing will remain paused until Complete transfer request is sent.

.. list-table::
   :widths: 30, 45, 25
   :header-rows: 1
   :class: longtable

   * - Parameter Name
     - Description
     - Value
   * - :code:`transferFeeList`
     -
     - | ``Type``: **Object**
   * - :code:`transferFeeList.assignedId`
     - Aliased payment gateway name.
     - | ``Type``: String
   * - :code:`transferFeeList.commissionCentis`
     - Amount of commission to be held in centis, 1.00 EUR = 100 centis.
     - | ``Type``: Integer
   * - :code:`transferFeeList.currency`
     - Upper case letters (ISO 4217 alpha code).
     - | ``Type``: String
   * - :code:`state`
     - In addition to the values from :ref:`Status Transfer<api_transfer_status>`, ``TRANSFER_FEE_REQUEST`` value only exists in this flow.
     - | ``Type``: String

Fail Response Parameters
^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
   :widths: 30, 45, 25
   :header-rows: 1
   :class: longtable

   * - Parameter Name
     - Description
     - Value
   * - :code:`error`
     -
     - | ``Type``: **Object**
   * - :code:`error.cause`
     - Cause of the error. Possible values: ``FILTERED``, ``INVALID_REQUEST``, ``INTERNAL_ERROR``, ``PROCESSING_FAILED``, ``ORDER_NOT_FOUND``.
     - | ``Type``: Enum
   * - :code:`error.code`
     - The unique error code.
     - | ``Type``: String
   * - :code:`error.message`
     - Description of the error.
     - | ``Type``: String
   * - :code:`invoiceId`
     - Transfer transaction identifier.
     - | ``Type``: String

Request Example
^^^^^^^^^^^^^^^

.. code-block:: json

  {
    "session": {
      "accessToken": "string",
      "token": "string"
    }
  }

Success Response Example
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: json

  {
    "bankOrderId": "string",
    "invoiceId": "string",
    "redirectUrl": "string",
    "session": {
      "token": "string"
    },
    "state": "enum"
  }

Success Response Example for Consumer defined transfer rates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

|
| **The following structure extends the default Transfer status response body (e.g. 2 processing gates):**

|

.. code-block:: json

    {
      "bankOrderId": "string",
      "invoiceId": "string",
      "redirectUrl": "string",
      "session": {
        "token": "string"
      },
      "state": "TRANSFER_FEE_REQUEST",
      "transferFeeList": [
        {
          "assignedId": "string",
          "commissionCentis": "integer",
          "currency": "string"
        },
        {
          "assignedId": "string",
          "commissionCentis": "integer",
          "currency": "string"
        }
      ]
    }

Fail Response Example
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: json

  {
    "error": {
      "cause": "enum",
      "code": "string",
      "message": "string"
    },
    "invoiceId": "string"
  }

Request Builder
^^^^^^^^^^^^^^^

.. raw:: html
      :file: ../../_static/examples/dapi_Transfer_Status_Debug.html