.. _/api/v2/void/:

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

.. contents::
  :local:

.. role:: ex

.. role:: code

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

:ex:`Void` can only be processed for :ex:`Sale` and :ex:`Capture` transactions in the final successful status (See :ref:`statuses`). To make a void request send an :code:`HTTPS POST` request to the :ref:`URLs<api_v2_void_request_url>` and the :ref:`parameters<api_v2_void_request_parameters_url>`. Use :ref:`SHA-1<SHA1>` for authentication.

.. _api_v2_void_request_url:

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


.. _api_v2_void_request_parameters_url:

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

.. note::
  | Request must have content-type=application/x-www-form-urlencoded.

.. warning::
  The following characters must be escaped in the parameter values: :code:`&` :code:`+` :code:`"`.

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

  * - Parameter Name
    - Description
    - Value
  * - :code:`login`
    - Connecting Party login name.
    - | ``Necessity``: Mandatory
      | ``Type``: String
      | ``Length``: 20
  * - :code:`orderid`
    - Unique order identifier assigned by Payneteasy system.
    - | ``Necessity``: Mandatory
      | ``Type``: String
      | ``Length``: 20
  * - :code:`client_orderid`
    - Unique Connecting Party identifier.
    - | ``Necessity``: Mandatory
      | ``Type``: Numeric
      | ``Length``: 10
  * - :code:`amount`
    - This optional parameter specifies amount to be reversed.
    - | ``Necessity``: Mandatory
      | ``Type``: String
      | ``Length``: 10
  * - :code:`currency`
    - Currency the transaction is charged in (See: :ref:`Currency codes<currency_codes>`). Sample values are: :ex:`USD` for US Dollar :ex:`EUR` for European Euro.
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 3
  * - :code:`control`
    - | Checksum generated by :ref:`SHA-1<SHA1>`. Control string is represented as concatenation of the following parameters:
      | 1. Request parameter: :ex:`login`
      | 2. Request parameter: :ex:`client_orderid`
      | 3. Request parameter: :ex:`orderid`
      | 4. :ex:`merchant_control` (Control key assigned to Connecting Party account in the Payneteasy gateway system).
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`comment`
    - A brief description of reason.
    - | ``Necessity``: Mandatory
      | ``Type``: String
      | ``Length``: 50

.. _api_v2_void_response_parameters:

Response Parameters
^^^^^^^^^^^^^^^^^^^

.. note::
  | Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.

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

   * - Parameter Name
     - Description
   * - :code:`type`
     - The type of response. May be :ex:`async-response`, :ex:`validation-error`, :ex:`error`. If type equals :ex:`validation-error` or :ex:`error`, :ex:`error-message` and :ex:`error-code` parameters contain error details
   * - :code:`paynet-order-id`
     - Order id assigned to the order by Payneteasy.
   * - :code:`merchant-order-id`
     - Connecting Party order id.
   * - :code:`serial-number`
     - Unique number assigned by Payneteasy server to particular request from the Connecting Party.
   * - :code:`end-point-id`
     - Entry point used for processing this transaction.
   * - :code:`error-message`
     - If status is :ex:`error` this parameter contains the reason for decline or error details.
   * - :code:`error-code`
     - The error code is case of :ex:`error status`.

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

.. code-block:: guess

  POST /paynet/api/v2/void/39914 HTTP/1.1
  Host: sandbox.payneteasy.com
  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

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

.. 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

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

.. 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 Collection
^^^^^^^^^^^^^^^^^^

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

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

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