.. _api_initiate_transfer:

Initiate transfer
#################

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

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

| Initiate transfer is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_url_initiate_transfer>` and the :ref:`parameters<api_parameters_initiate_transfer>`.
| To initiate funds transfer, Connecting Party’s app sends :ex:`{accessToken}` with transaction amount and other device parameters to Connecting Party’s server, which are used to start a session with unique random :ex:`{nonce}` and encrypted :ex:`{signature}`.
| In response Connecting Party’s server also provides information about invoice in Connecting Party’s system and endpoint in Payneteasy.
| The Connecting Party's server may also respond with the transaction's commission.

.. _api_url_initiate_transfer:

API URLs
^^^^^^^^

.. note::
    | This is an example of URL format on Connecting Party server.

.. list-table::
   :widths: 100
   :header-rows: 1
   :class: longtable

   * - Connecting Party Server
   * - :ex:`https://proxy.connectingpartyserver.com/transfer/initiate-transfer`

.. _api_parameters_initiate_transfer:

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

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

   * - Parameter Name
     - Description
     - Value
   * - :code:`consumer`
     - |
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`consumer.device`
     - |
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`consumer.device.serialNumber`
     - Consumer's device serial number.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 1-50
   * - :code:`transaction`
     - |
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`transaction.amountCentis`
     - Transaction amount, 1.00 EUR = 100 centis.
     - | ``Necessity``: Required
       | ``Type``: Integer
   * - :code:`transaction.currency`
     - Upper case letters (ISO 4217 alpha code).
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 3
   * - :code:`session`
     - |
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`session.accessToken`
     - Access token key received in Optional consumer authentication.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 32-128
   * - :code:`consumer.device.imei`
     - Consumer's device international mobile equipment identity.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 14-16
   * - :code:`location`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`location.lat`
     - The latitude specified in the range of -90.0 through +90.0, both inclusive.
     - | ``Type``: Double
   * - :code:`location.lng`
     - The longitude specified in the range -180.0 through +180.0, both inclusive.
     - | ``Type``: Double
   * - :code:`consumer.ipAddresses`
     - Consumer's IP addresses.
     - | ``Type``: List
   * - :code:`consumer.ipAddresses[]`
     - Consumer's IP address.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 7-15
   * - :code:`fromBin`
     - Source of funds card BIN (first 6 digits of card number) may be used to display pre-calculated commission.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 6
   * - :code:`toBin`
     - Destination of funds card BIN (first 6 digits of card number) may be used to display pre-calculated commission.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 6

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

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

   * - Parameter Name
     - Description
     - Value
   * - :code:`endpointId`
     - Entry point identifier for transfer transaction.
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`invoiceId`
     - Transfer transaction identifier.
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`session`
     - |
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`session.nonce`
     - Unique random string generated by Connecting Party's server.
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`session.signature`
     - Checksum generated by hmac-sha1 (see :ref:`signature-computation`) from the concatenation of the accessToken, consumer.device.serialNumber, endpointId, session.nonce, invoiceId, transaction.amountCentis and the transaction.currency.
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`rates`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`rates.min`
     - Possible minimum commission amount.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`rates.max`
     - Possible maximum commission amount.
     - | ``Necessity``: Optional
       | ``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``, ``SERVER_FAILED``, ``SERVER_UNAVAILABLE``.
     - | ``Type``: Enum
   * - :code:`error.code`
     - The unique error code.
     - | ``Type``: String
   * - :code:`error.message`
     - Description of the error.
     - | ``Type``: String

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

.. code-block:: json

  {
    "consumer": {
      "device": {
        "imei": "string",
        "serialNumber": "string"
      },
      "ipAddresses": ["string"]
    },
    "location": {
      "lat": "double",
      "lng": "double"
    },
    "session": {
      "accessToken": "string"
    },
    "transaction": {
      "amountCentis": "integer",
      "currency": "string"
    }
  }

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

.. code-block:: json

  {
    "endpointId": "string",
    "invoiceId": "string",
    "rates": {
      "min": "string",
      "max": "string"
    },
    "session": {
      "nonce": "string",
      "signature": "string"
    }
  }

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

.. code-block:: json

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