.. _api_initiate_verification:

Initiate verification
#####################

.. toctree::
    :maxdepth: 1

.. contents::
    :local:

.. role:: ex

.. role:: code

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

| Initiate verification is initiated through :code:`HTTPS POST` request by using :ref:`URLs<api_url_initiate_verification>` and the :ref:`parameters<api_parameters_initiate_verification>`.
| To initiate card verification, Connecting Party’s app sends :ex:`{accessToken}` with other device parameters to Connecting Party’s server. These parameters are used to start a session with unique random :ex:`{nonce}` and encrypted :ex:`{signature}`. In response Connecting Party’s server also provides information about :ex:`{invoiceId}` in Connecting Party’s system and :ex:`{endpointId}` in Payneteasy.

.. _api_url_initiate_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/initiate-verification`

.. _api_parameters_initiate_verification:

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:`transaction`
     - |
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`transaction.currency`
     - | Upper case letters (ISO 4217 alpha code).
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 3
   * - :code:`session`
     - |
     - | ``Necessity``: Required
       | ``Type``: **Object**
   * - :code:`session.accessToken`
     - | Access token key received in Optional consumer authentication.
     - | ``Necessity``: Required
       | ``Type``: String
       | ``Length``: 32-128
   * - :code:`consumer.device.imei`
     - | Consumer's device international mobile equipment identity.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 14-16
   * - :code:`location`
     - |
     - | ``Necessity``: Optional
       | ``Type``: **Object**
   * - :code:`location.lat`
     - | The latitude specified in the range of -90.0 through +90.0, both inclusive.
     - | ``Necessity``: Optional
       | ``Type``: Double
   * - :code:`location.lng`
     - | The longitude specified in the range -180.0 through +180.0, both inclusive.
     - | ``Necessity``: Optional
       | ``Type``: Double
   * - :code:`consumer.ipAddresses`
     - | Consumer's IP addresses.
     - | ``Necessity``: Optional
       | ``Type``: List
   * - :code:`consumer.ipAddresses[]`
     - | Consumer's IP address.
     - | ``Necessity``: Optional
       | ``Type``: String
       | ``Length``: 7-15

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

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

   * - Parameter Name
     - Description
     - Value
   * - :code:`endpointId`
     - Entry point identifier for verification transaction.
     - | ``Type``: String
   * - :code:`invoiceId`
     - Verification transaction identifier.
     - | ``Type``: String
   * - :code:`session`
     -
     - | ``Type``: **Object**
   * - :code:`session.nonce`
     - Unique random string generated by Connecting Party's server.
     - | ``Type``: String
   * - :code:`session.signature`
     - Checksum generated by hmac-sha1 (see :ref:`signature-computation`) from the concatenation of accessToken, consumer.device.serialNumber, endpointId, session.nonce, invoiceId and transaction.currency.
     - | ``Type``: String

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

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

.. code-block:: json

  {
    "consumer": {
      "device": {
        "imei": "string",
        "serialNumber": "string"
      },
      "ipAddresses": ["string"]
    },
    "location": {
      "lat": "double",
      "lng": "double"
    },
    "session": {
      "accessToken": "string"
    },
    "transaction": {
      "currency": "string"
    }
  }

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

.. code-block:: json

  {
    "endpointId": "string",
    "invoiceId": "string",
    "session": {
      "nonce": "string",
      "signature": "string"
    }
  }


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

.. code-block:: json

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