.. _api_check_verification:

Check verification
##################

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

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

| Check verification is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_url_check_verification>` and the :ref:`parameters<api_parameters_check_verification>`.
| Check verification 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_verification:

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/verification/{invoiceId}/check`

.. _api_parameters_check_verification:

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

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

   * - Parameter Name
     - Description
     - Value
   * - :code:`consumer`
     -
     - | ``Type``: **Object**
   * - :code:`consumer.device`
     -
     - | ``Type``: **Object**
   * - :code:`consumer.device.serialNumber`
     - Consumer's device serial number.
     - | ``Type``: String
       | ``Length``: 1-50
   * - :code:`session`
     -
     - | ``Type``: **Object**
   * - :code:`session.accessToken`
     - Consumer's access token key sent by Connecting Party's app.
     - | ``Type``: String
       | ``Length``: 32-128
   * - :code:`session.nonce`
     - Value sent by Connecting Party's app.
     - | ``Type``: String
       | ``Length``: 32-128
   * - :code:`session.signature`
     - Value sent by Connecting Party's app.
     - | ``Type``: String
       | ``Length``: 32-128
   * - :code:`session.token`
     - The session token of verification transaction.
     - | ``Type``: String
       | ``Length``: 16-36

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

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

   * - Parameter Name
     - Description
     - Value
   * - :code:`invoiceId`
     - Verification 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 consumer.device.serialNumber, session.nonce, endpointId and invoiceId.
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`session.nonce`
     - Unique random string generated by Connecting Party's server in Initiate verification response.
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`session.token`
     - The session token of verification transaction.
     - | ``Necessity``: Required
       | ``Type``: String
   * - :code:`billing`
     - |
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`billing.address`
     - |
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`billing.address.city`
     - City name.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`billing.address.country`
     - ISO alpha3 country code.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`billing.address.postcodeZip`
     - ZIP post code.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`billing.address.state`
     - State is used if present. For example, Los Angeles is in CA state.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`billing.address.street`
     - Street is used for district names and street names.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`billing.address.street2`
     - Street 2 is used for long addresses. Usually it contains apartment and building №.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`billing.phone`
     - Customer's contact phone number.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`consumer.birthDay`
     - Consumer's birth day in "ddMMyyyy" format.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`consumer.email`
     - Consumer's email address.
     - | ``Necessity``: Optional
       | ``Type``: String
   * - :code:`consumer.ipAddresses`
     - Consumer's IP addresses.
     - | ``Necessity``: Optional
       | ``Type``: List
   * - :code:`consumer.ipAddresses[]`
     - Consumer's IP address.
     - | ``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`
     - Verification transaction identifier.
     - | ``Type``: String

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

.. code-block:: json

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

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

.. code-block:: json

  {
    "billing": {
      "address": {
        "city": "string",
        "country": "string",
        "postcodeZip": "string",
        "state": "string",
        "street": "string",
        "street2": "string"
      },
      "phone": "string"
    },
    "consumer": {
      "birthDay": "string",
      "email": "string",
      "ipAddresses": ["string"]
    },
    "invoiceId": "string",
    "session": {
      "checkSignature": "string",
      "nonce": "string",
      "token": "string"
    },
    "transaction": {
      "currency": "string",
      "randomSumCentis": "integer"
    }
  }

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

.. code-block:: json

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