.. _api_check_sale:

Check sale
##########

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

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

| Check sale is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_url_check_sale>` and the :ref:`parameters<api_parameters_check_sale>`.
| Check sale is used for security purposes and allows Payneteasy to compare the data sent by Connecting Party’s app with the data stored on Connecting Party’s server.
| It is highly recommended to respond with the actual information stored on Connecting Party’s server.

.. _api_url_check_sale:

API URLs
^^^^^^^^

.. note::
    | This is an example of URL format on Connecting Party server.

.. list-table::
   :widths: 100
   :header-rows: 1
   :class: longtable

   * - Connecting Party Server
   * - :ex:`https://proxy.connectingpartyserver.com/sale/{invoiceId}/check`

.. _api_parameters_check_sale:

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:`session`
     - |
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`session.accessToken`
     - Consumer's access token key sent by Connecting Party's app.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 32-128
   * - :code:`session.nonce`
     - Value sent by Connecting Party's app.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 32-128
   * - :code:`session.signature`
     - Value sent by Connecting Party's app.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 32-128
   * - :code:`session.token`
     - The session token of sale transaction.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 16-36
   * - :code:`sourceOfFunds`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`sourceOfFunds.reference`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`sourceOfFunds.reference.clientCardId`
     - The source card reference identifier (on client side) if sent in Perform sale request.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 1-128

Success Response Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

   * - Parameter Name
     - Description
     - Value
   * - :code:`invoiceId`
     - Sale transaction identifier
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`session`
     - |
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`session.checkSignature`
     - Checksum generated by hmac-sha1 (see :ref:`signature-computation`) from the concatenation of the consumer.device.serialNumber, session.nonce, endpointId, invoiceId, sourceOfFunds.reference.serverCardId (if present).
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`session.nonce`
     - Unique random string generated by Connecting Party's server in Initiate sale response.
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`session.token`
     - The session token of sale transaction.
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`consumer.email`
     - Сonsumer's email address, if sent in original card mapping transaction.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`sourceOfFunds`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`sourceOfFunds.reference`
     -
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`sourceOfFunds.reference.serverCardId`
     - The source card reference identifier (on server side).
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`transaction.currency`
     - Upper case letters (ISO 4217 alpha code).
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`transaction.randomSumCentis`
     - Random sum amount (for random sum check), 1.00 EUR = 100 centis.
     - | ``Necessity``: Optional
       | ``Type``: Integer

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: ``FILTERED``, ``INVALID_REQUEST``, ``SERVER_FAILED``, ``SERVER_UNAVAILABLE``.
     - | ``Type``: Enum
   * - :code:`error.code`
     - The unique error code.
     - | ``Type``: String
   * - :code:`error.message`
     - Description of the error.
     - | ``Type``: String
   * - :code:`invoiceId`
     - Sale transaction identifier.
     - | ``Type``: String

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

.. code-block:: json

  {
    "consumer": {
      "device": {
        "serialNumber": "string"
      }
    },
    "session": {
      "accessToken": "string",
      "nonce": "string",
      "signature": "string",
      "token": "string"
    },
    "sourceOfFunds": {
      "reference": {
        "clientCardId": "string"
      }
    }
  }

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

.. code-block:: json

  {
    "consumer": {
      "email": "string"
    },
    "invoiceId": "string",
    "session": {
      "checkSignature": "string",
      "nonce": "string",
      "token": "string"
    },
    "sourceOfFunds": {
      "card": {
        "expiry": {
          "month": "integer",
          "year": "integer"
        },
        "holder":{
          "firstName": "string",
          "lastName": "string"
        },
        "number": "string"
      },
      "reference": {
        "serverCardId": "string",
      }
    },
    "transaction": {
      "currency": "string",
      "randomSumCentis": "integer"
    }
  }

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

.. code-block:: json

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