.. meta::
   :description: /api/v2/void API endpoint Payneteasy: отменяет авторизованную, но ещё не рассчитанную транзакцию, возвращая удержанные средства держателю карты.

.. _/api/v2/void/:

/api/v2/void
#############


.. role:: ex

.. role:: code

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

:ex:`Void` может быть обработан только для транзакций :ex:`Sale` и :ex:`Capture` с финальным успешным статусом (см. :ref:`statuses`). Чтобы выполнить запрос Void, отправьте запрос :code:`HTTPS POST` на указанные :ref:`URL<api_v2_void_request_url>` и :ref:`параметры<api_v2_void_request_parameters_url>`. Для аутентификации используйте :ref:`SHA-1<SHA1>`.

.. _api_v2_void_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/void/ENDPOINTID`
     - :ex:`https://gate.payneteasy.ru/paynet/api/v2/void/ENDPOINTID`
   * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/void/group/ENDPOINTGROUPID`
     - :ex:`https://gate.payneteasy.ru/paynet/api/v2/void/void/ENDPOINTGROUPID`


.. _api_v2_void_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`
    - Уникальный идентификационный номер Присоединяющейся Стороны.
    - | ``Необходимость``: Обязательно
      | ``Тип``: Numeric
      | ``Длина``: 10
  * - :code:`amount`
    - Этот необязательный параметр указывает сумму для Reversal.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 10
  * - :code:`currency`
    - Валюта, в которой проводится операция (см. :ref:`Коды валют<currency_codes>`). Примеры значений: :ex:`USD` для доллара США, :ex:`EUR` для европейского евро, RUB для российского рубля.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 3
  * - :code:`control`
    - | Контрольная сумма, сгенерированная :ref:`SHA-1<SHA1>`. Строка для подписи представляет собой объединение следующих параметров:
      | 1. Параметр запроса: :ex:`login`
      | 2. Параметр запроса: :ex:`client_orderid`
      | 3. Параметр запроса: :ex:`orderid`
      | 4. :ex:`merchant_control` (Контрольный ключ, назначенный для аккаунта Присоединяющейся стороны в системе Payneteasy).
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`comment`
    - Краткое описание.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 50

.. _api_v2_void_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/void/39914 HTTP/1.1
  Host: sandbox.payneteasy.ru
  User-Agent: curl/7.83.0
  Accept: */*
  Content-Length: 123
  Content-Type: application/x-www-form-urlencoded
  Connection: close

  login=Test
  &client_orderid=55
  &orderid=6862995
  &comment=Service not provided
  &control=246e0a2074f9e4b84cff59b2567ed48ec3aab87d

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

.. code-block:: none

   HTTP/1.1 200 OK
   Server: server
   Date: Tue, 16 Aug 2022 06:57:40 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: 138

   type=async-response
   &serial-number=00000000-0000-0000-0000-000002ddae76
   &merchant-order-id=55
   &paynet-order-id=6862995
   &end-point-id=39914

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

.. code-block:: none

   HTTP/1.1 200 OK
   Server: server
   Date: Tue, 16 Aug 2022 07:21:37 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: 148

   type=validation-error
   &serial-number=00000000-0000-0000-0000-000002ddae78
   &merchant-order-id=Test
   &error-message=INVALID_CONTROL_CODE
   &error-code=2

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

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

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

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