.. _/api/v2/return/:

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

.. contents::
  :local:

.. role:: ex

.. role:: code

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

:ex:`Return` transactions may only be initiated when the transaction have final successful status. See :ref:`statuses`. For :ex:`Preauth` it makes :ex:`Cancel` transaction, for :ex:`Capture` and :ex:`Sale` – :ex:`Reversal`. :ex:`Return` transactions are initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_v2_return_request_url>` and the :ref:`parameters<api_v2_return_request_parameters_url>` specified below. Use :ref:`SHA-1<SHA1>` for authentication.

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


.. _api_v2_return_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``: String
      | ``Length``: 128
  * - :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. Request parameter: :ex:`amount` (in minor units, if sent).
      | 5. Request parameter: :ex:`currency` (if sent).
      | 6. :ex:`merchant_control` (Control key assigned to Connecting Party account in the Payneteasy gateway system).
    - | ``Necessity``: Conditional
      | ``Type``: String
      | ``Length``: 128
  * - :code:`amount`
    - The amount has to be specified in the highest units with :ex:`.` delimiter. For instance, :ex:`10.5` for :ex:`USD` means 10 US Dollars and 50 Cents. If this parameter is omitted, initial transaction is reversed as a whole. Amount only makes sense for :ex:`reversals`, not :ex:`cancels`. Amount cannot exceed initial transaction amount. Please note that Currency MUST be specified if amount is specified!
    - | ``Necessity``: Mandatory
      | ``Type``: Numeric
      | ``Length``: 10
  * - :code:`currency`
    - Currency in which amount is specified. Provided in three-letter currency code format. Example: USD for US Dollar. Reference: :ref:`Currency Codes<currency_codes>`.
    - | ``Necessity``: Mandatory
      | ``Type``: String
      | ``Length``: 50
  * - :code:`comment`
    - A brief description of reason.
    - | ``Necessity``: Mandatory
      | ``Type``: String
      | ``Length``: 50

.. _return_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/return/39914 HTTP/1.1
  Host: sandbox.payneteasy.com
  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

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

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

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

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

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

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

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