.. _api_perform_transfer:

Perform transfer
################

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

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

| Perform transfer is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_url_perform_transfer>` and the :ref:`parameters<api_parameters_perform_transfer>`.
| On this stage Connecting Party’s app sends cardholder, device, session data and other parameters straight to Payneteasy to perform funds transfer from card to card.
| A lot of criteria checks and filters may be applied, such as BIN, currency, country, blacklisted or not, etc. Depending on the integration, these settings may be customizable.

.. _api_url_perform_transfer:

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}`
     - :ex:`https://gate.payneteasy.com/paynet/dapi/v1/transfer/{endpointId}/{invoiceId}`

.. _api_parameters_perform_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:`consumer.email`
     - Сonsumer's email address, if sent in original card mapping transaction and card reference is being used instead of cardholder data.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 3-128
   * - :code:`destinationOfFunds`
     -
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`destinationOfFunds.card`
     - Only one of these subtypes (card, reference) should be used.
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`destinationOfFunds.card.number`
     - Destination card number (PAN).
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 9-19
   * - :code:`destinationOfFunds.reference`
     - Only one of these subtypes (card, reference) should be used.
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`destinationOfFunds.reference.clientCardId`
     - Destination card reference identifier (on client side).
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 1-128
   * - :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:`session.nonce`
     - Value received in Initiate transfer response.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 32-128
   * - :code:`session.signature`
     - Value received in Initiate transfer response.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 32-128
   * - :code:`sourceOfFunds`
     -
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`sourceOfFunds.card`
     - Only one of these subtypes (card, reference) should be used.
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`sourceOfFunds.card.expiry`
     -
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`sourceOfFunds.card.expiry.month`
     - Source Card expiration month.
     - | ``Necessity``: Required
       | ``Type``: Integer
       | ``Length``: 2
   * - :code:`sourceOfFunds.card.expiry.year`
     - Source Card expiration year.
     - | ``Necessity``: Required
       | ``Type``: Integer
       | ``Length``: 4
   * - :code:`sourceOfFunds.card.holder`
     -
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`sourceOfFunds.card.holder.firstName`
     - Cardholder's first name.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 1-50
   * - :code:`sourceOfFunds.card.holder.lastName`
     - Cardholder's last name.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 1-50
   * - :code:`sourceOfFunds.card.holder.printedName`
     - Cardholder's printed name (first and last name together). May be used instead of firstName + lastName.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 1-50
   * - :code:`sourceOfFunds.card.number`
     - Source card number (PAN).
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 9-19
   * - :code:`sourceOfFunds.card.securityCode`
     - Source card security code (CVV).
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 3-4
   * - :code:`sourceOfFunds.reference`
     - only one of these subtypes (card, reference) should be used.
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`sourceOfFunds.reference.clientCardId`
     - Source card reference identifier (on client side).
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 1-128
   * - :code:`sourceOfFunds.reference.securityCode`
     - Source card security code (CVV).
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 3-4
   * - :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:`location`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`location.lat`
     - The latitude specified in the range of -90.0 through +90.0, both inclusive.
     - | ``Necessity``: Optional
       | ``Type``: Double
   * - :code:`location.lng`
     - The longitude specified in the range -180.0 through +180.0, both inclusive.
     - | ``Necessity``: Optional
       | ``Type``: Double
   * - :code:`billing`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`billing.address`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`billing.address.city`
     - City name.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 1-100
   * - :code:`billing.address.country`
     - ISO alpha3 country code.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 3
   * - :code:`billing.address.postcodeZip`
     - ZIP post code.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 1-10
   * - :code:`billing.address.state`
     - State is used if present. For example, Los Angeles is in CA state.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 2-3
   * - :code:`billing.address.street`
     - Street is used for district names and street names.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 1-50
   * - :code:`billing.address.street2`
     - Street 2 is used for long addresses. Usually it contains apartment and building №.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 1-50
   * - :code:`billing.phone`
     - Сonsumer's contact phone number.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 1-20
   * - :code:`consumer.birthDay`
     - Сonsumer's birth day in "ddMMyyyy" format.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 8
   * - :code:`consumer.device.imei`
     - Сonsumer's device international mobile equipment identity.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 14-16
   * - :code:`consumer.ipAddresses`
     - Сonsumer's IP addresses.
     - | ``Necessity``: Optional
       | ``Type``: List
   * - :code:`consumer.ipAddresses[]`
     - Сonsumer's IP address.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 7-15
   * - :code:`order`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`order.description`
     - Brief transaction description. May be mandatory for certain Acquirer Banks.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 128
   * - :code:`order.siteUrl`
     - URL of website associated with the transaction.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 128
   * - :code:`order.purpose`
     - May be used for better transaction control or additional checks.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 128

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

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: ``INVALID_REQUEST``, ``INVALID_CONFIGURATION``, ``INTERNAL_ERROR``, ``PROCESSING_FAILED``.
     - | ``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

  {
    "billing": {
      "address": {
        "city": "string",
        "country": "string",
        "postcodeZip": "string",
        "state": "string",
        "street": "string",
        "street2": "string"
      },
      "phone": "string"
    },
    "consumer": {
      "birthDay": "string",
      "device": {
        "imei": "string",
        "serialNumber": "string"
      },
      "email": "string",
      "ipAddresses": ["string"]
    },
    "destinationOfFunds": {
      "card": {
        "number": "string",
      },
      "reference": {
        "clientCardId": "string"
      }
    },
    "location": {
      "lat": "double",
      "lng": "double"
    },
    "order": {
      "description": "string",
      "siteUrl": "string",
      "purpose": "string"
    },
    "session": {
      "accessToken": "string",
      "nonce": "string",
      "signature": "string"
    },
    "sourceOfFunds": {
      "card": {
        "expiry": {
          "month": "integer",
          "year": "integer"
        },
        "holder":{
          "firstName": "string",
          "lastName": "string"
        },
        "number": "string",
        "securityCode": "string"
      },
      "reference": {
        "clientCardId": "string",
        "securityCode": "string"
      }
    },
    "transaction": {
      "amountCentis": "integer",
      "currency": "string"
    }
  }

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

.. code-block:: json

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

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

.. code-block:: json

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

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

| For integration purposes use :ref:`test_cards` to generate random card numbers.
|

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