.. meta::
   :description: Эндпоинт API /api/v2/return Payneteasy: возврат ранее одобренной транзакции Sale или Capture на полную или частичную сумму через API.

.. _/api/v2/return/:

/api/v2/return
##############################


.. role:: ex

.. role:: code

Введение
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Транзакции :ex:`Return` можно инициировать только после получения транзакцией окончательного успешного статуса. См. :ref:`statuses`. Для :ex:`Preauth` создаётся транзакция :ex:`Cancel`, для :ex:`Capture` и :ex:`Sale` — :ex:`Reversal`. Транзакции :ex:`Return` инициируются запросом :code:`HTTPS POST` с использованием указанных ниже :ref:`URL-адресов<api_v2_return_request_url>` и :ref:`параметров<api_v2_return_request_parameters_url>`. Для аутентификации используйте :ref:`SHA-1<SHA1>`.

.. _api_v2_return_request_url:

API URL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
    | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее.

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

   * - Интеграционная среда
     - Производственная среда
   * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/return/ENDPOINTID`
     - :ex:`https://gate.payneteasy.ru/paynet/api/v2/return/ENDPOINTID`
   * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/return/group/ENDPOINTGROUPID`
     - :ex:`https://gate.payneteasy.ru/paynet/api/v2/return/group/ENDPOINTGROUPID`


.. _api_v2_return_request_parameters_url:

Параметры запроса
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
  | Запрос должен иметь заголовок content-type=application/x-www-form-urlencoded.

.. warning::
  В значениях параметров необходимо экранировать следующие символы: :code:`&` :code:`+` :code:`"`.

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

  * - Название параметра
    - Описание
    - Значение
  * - :code:`login`
    - Логин Присоединяющейся Стороны в Платёжном Шлюзе.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 20
  * - :code:`orderid`
    - Уникальный идентификационный номер транзакции, присвоенный системой Payneteasy.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 20
  * - :code:`client_orderid`
    - Уникальный идентификационный номер Присоединяющейся Стороны.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`control`
    - | Контрольная сумма, сгенерированная :ref:`SHA-1<SHA1>`. Строка для подписи представляет собой объединение следующих параметров:
      | 1. Параметр запроса::ex:`login`.
      | 2. Параметр запроса::ex:`client_orderid`.
      | 3. Параметр запроса::ex:`orderid`.
      | 4. Параметр запроса: :ex:`amount` (в минимальных единицах).
      | 5. Параметр запроса: :ex:`currency`.
      | 6.:ex:`merchant_control` (Контрольный ключ, назначенный для учетной записи Присоединяющейся Cтороны в Payneteasy).
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`amount`
    - Сумма должна быть указана в минимальных единицах с :ex:`.` разделителем. Например, :ex:`100.5` в :ex:`RUB` означает 100 российских рублей и 50 копеек. Если данный параметр пропущен, будет произведен возврат всей суммы. Данный параметр имеет смысл для :ex:`возвратов`, но не :ex:`отмены`. Сумма не может быть больше изначальной суммы транзакции. Важно! Если указана сумма, необходимо также указать валюту! 
    - | ``Необходимость``: Обязательно
      | ``Тип``: Numeric
      | ``Длина``: 10
  * - :code:`currency`
    - Валюта, в которой проводится операция (см. :ref:`Коды валют<currency_codes>`). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля. 
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 50
  * - :code:`comment`
    - Краткое описание.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 50

.. _return_response_parameters:

Параметры ответа
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
  | Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра.

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

   * - Название параметра
     - Описание
   * - :code:`type`
     - Тип ответа. Может принимать такие значения как: :ex:`async-response`, :ex:`validation-error`, :ex:`error` и т.д. Если тип ответа :ex:`validation-error` или :ex:`error`, параметры :ex:`error-message` и :ex:`error-code` будут содержать детали ошибки.
   * - :code:`paynet-order-id`
     - Идентификатор заказа, присвоенный Payneteasy.
   * - :code:`merchant-order-id`
     - Идентификатор заказа Присоединяющейся Стороны.
   * - :code:`serial-number`
     - Уникальный номер, присваиваемый сервером Payneteasy конкретному запросу от Присоединяющейся стороны.
   * - :code:`end-point-id`
     - Идентификатор терминала, используемый для транзакции.
   * - :code:`error-message`
     - Для транзакций в статусе :ex:`error` этот параметр будет содержать причину отклонения или сведения об ошибке.
   * - :code:`error-code`
     - Код ошибки для транзакций в статусе :ex:`error`.

Пример запроса
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: guess

  POST /paynet/api/v2/return/39914 HTTP/1.1
  Host: sandbox.payneteasy.ru
  User-Agent: curl/7.83.0
  Accept: */*
  Content-Length: 162
  Content-Type: application/x-www-form-urlencoded
  Connection: close

  login=TestMerchant
  &client_orderid=Test
  &orderid=6862958
  &amount=5.00
  &currency=RUB
  &comment=Service not provided
  &control=2dfdb99c4eff5b31c978ecb8bc4b4d094e24c1d4

Пример успешного ответа
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: none

  HTTP/1.1 200 OK
  Server: server
  Date: Mon, 08 Aug 2022 07:50:08 GMT
  Content-Type: text/html;charset=utf-8
  Connection: close
  Vary: Accept-Encoding
  X-XSS-Protection: 1
  X-Content-Type-Options: nosniff
  Strict-Transport-Security: max-age=31536000
  Content-Language: en-US
  Strict-Transport-Security: max-age=31536000
  Content-Length: 141

  type=async-response
  &serial-number=00000000-0000-0000-0000-000002ddad4a
  &merchant-order-id=Test
  &paynet-order-id=6862958
  &end-point-id=39914

Пример неуспешного ответа
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: none

  HTTP/1.1 200 OK
  Server: server
  Date: Mon, 08 Aug 2022 10:45:32 GMT
  Content-Type: text/html;charset=utf-8
  Connection: close
  Vary: Accept-Encoding
  X-XSS-Protection: 1
  X-Content-Type-Options: nosniff
  Strict-Transport-Security: max-age=31536000
  Content-Language: en-US
  Strict-Transport-Security: max-age=31536000
  Content-Length: 153

  type=validation-error
  &serial-number=00000000-0000-0000-0000-000002ddad5c
  &error-message=Reversal+currency+does+not+match+project+currency
  &error-code=16

Коллекция Postman
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. raw:: html
    :file: ../_static/Postman/Postman_return.html

Конструктор запросов
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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