.. meta::
   :description: Уведомление сопоставления карты Sale в потоке Mobile Device Server Payneteasy: callback, передающий ссылку на сопоставленную карту после продажи, инициированной с мобильного устройства.

.. _api_sale_card_mapping_notification:

Уведомление о сопоставлении карты Sale
##############################


.. role:: ex

.. role:: code

Введение
^^^^^^^^^^^^

| Уведомление о сопоставлении карты Sale инициируется запросом :code:`HTTPS POST` с использованием :ref:`URL-адресов<api_url_sale_card_mapping_notification>` и :ref:`параметров<api_parameters_sale_card_mapping_notification>`.
| Уведомление о сопоставлении карт позволяет сопоставлять учётные данные Consumer (телефон, e-mail, адрес выставления счёта, имя в Twitter и т. д.) с данными карты. Сопоставления можно использовать в транзакциях Transfer или Sale вместо номеров карт и иной информации о держателе карты. Payneteasy отправляет запрос уведомления о сопоставлении карты Sale на сервер/прокси Присоединяющейся стороны с созданной на своей стороне ссылкой на карту — :ex:`{serverCardId}`.
| Сервер Присоединяющейся стороны сопоставляет :ex:`{serverCardId}` с созданным на своей стороне :ex:`{clientCardId}`. Затем этот :ex:`{clientCardId}` может быть сопоставлен в приложении или на сервере Присоединяющейся стороны с любыми данными Consumer из исходного запроса Perform sale. Это позволяет приложению Присоединяющейся стороны обрабатывать транзакции Sale или Transfer по электронному адресу Consumer, номеру телефона и т. д.
| :ex:`{uniqueReferenceCardId}` остаётся прежним, если потребитель выполняет другую транзакцию с тем же номером карты, но, например, другой датой истечения срока. Присоединяющаяся сторона может использовать его для программ лояльности или контроля мошенничества.
| Приложение Присоединяющейся стороны создаёт новые запросы Sale, используя :ex:`{clientCardId}` вместо данных исходной карты. Payneteasy отправляет этот :ex:`{clientCardId}` на сервер Присоединяющейся стороны в «Check sale request» и получает сопоставленный с ним :ex:`{serverCardId}` в «Check sale response» от сервера Присоединяющейся стороны, который используется для продолжения обработки этой транзакции.
| :ex:`{serverCardId}` карты-источника или проверенной карты можно использовать для новых транзакций Sale и как источник или получатель для новых транзакций Transfer.

.. _api_url_sale_card_mapping_notification:

API URL
^^^^^^^^

.. note::
    | Это пример URL на сервере Присоединяющейся Стороны.

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

   * - Сервер Присоединяющейся Стороны
   * - :ex:`https://proxy.connectingpartyserver.com/sale/notification`

.. _api_parameters_sale_card_mapping_notification:

Параметры запроса
^^^^^^^^^^^^^^^^^^

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

   * - Название параметра
     - Описание
     - Значение
   * - :code:`consumer`
     - |
     - | ``Необходимость``: Обязательно
       | ``Тип``: **Object**
   * - :code:`consumer.device`
     - |
     - | ``Необходимость``: Обязательно
       | ``Тип``: **Object**
   * - :code:`consumer.device.serialNumber`
     - Серийный номер устройства потребителя.
     - | ``Необходимость``: Обязательно
       | ``Тип``: String
       | ``Длина``: 1-50
   * - :code:`session`
     - |
     - | ``Необходимость``: Обязательно
       | ``Тип``: **Object**
   * - :code:`session.accessToken`
     - Ключ токена доступа потребителя.
     - | ``Необходимость``: Обязательно
       | ``Тип``: String
       | ``Длина``: 32-128
   * - :code:`session.token`
     - Session token транзакции sale.
     - | ``Необходимость``: Обязательно
       | ``Тип``: String
       | ``Длина``: 16-36
   * - :code:`sourceCard`
     -
     - | ``Необходимость``: Опционально
       | ``Тип``: **Object**
   * - :code:`sourceCard.bin`
     - BIN исходной карты.
     - | ``Необходимость``: Опционально
       | ``Тип``: Integer
   * - :code:`sourceCard.reference`
     -
     - | ``Необходимость``: Опционально
       | ``Тип``: **Object**
   * - :code:`sourceCard.reference.serverCardId`
     - Ссылочный идентификатор исходной карты (на стороне сервера).
     - | ``Необходимость``: Опционально
       | ``Тип``: String
       | ``Length``: 1-64
   * - :code:`sourceCard.reference.uniqueReferenceCardId`
     - Уникальный идентификатор исходной карты (на стороне сервера).
     - | ``Необходимость``: Опционально
       | ``Тип``: Integer

Параметры успешного ответа
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

   * - Название параметра
     - Описание
     - Значение
   * - :code:`invoiceId`
     - Идентификатор транзакции sale.
     - | ``Тип``: String
   * - :code:`session`
     -
     - | ``Тип``: **Object**
   * - :code:`session.checkSignature`
     - Контрольная сумма, сгенерированная hmac-sha1 (см. :ref:`signature-computation`) из конкатенации session.nonce, endpointId и invoiceId.
     - | ``Тип``: String
   * - :code:`session.nonce`
     - Уникальная случайная строка, сгенерированная сервером Присоединяющейся стороны.
     - | ``Тип``: String
   * - :code:`session.token`
     - Session token транзакции sale.
     - | ``Тип``: String

Параметры неуспешного ответа
^^^^^^^^^^^^^^^^^^^^^^^^

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

   * - Название параметра
     - Описание
     - Значение
   * - :code:`error`
     -
     - | ``Тип``: **Object**
   * - :code:`error.cause`
     - Причина ошибки. Возможные значения: ``FILTERED``, ``INVALID_REQUEST``, ``SERVER_FAILED``, ``SERVER_UNAVAILABLE``.
     - | ``Тип``: Enum
   * - :code:`error.code`
     - Уникальный код ошибки.
     - | ``Тип``: String
   * - :code:`error.message`
     - Описание ошибки.
     - | ``Тип``: String
   * - :code:`invoiceId`
     - Идентификатор транзакции sale.
     - | ``Тип``: String

Пример запроса
^^^^^^^^^^^^^^^

.. code-block:: json

  {
    "consumer": {
      "device": {
        "serialNumber": "string"
      }
    },
    "session": {
      "accessToken": "string",
      "token":"string"
    },
    "sourceCard": {
      "bin": "integer",
      "reference": {
        "serverCardId": "string",
        "uniqueReferenceCardId": "integer"
      }
    }
  }

Пример успешного ответа
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: json

  {
    "invoiceId": "string",
    "session": {
      "checkSignature": "string",
      "nonce": "string",
      "token": "string"
    }
  }

Пример неуспешного ответа
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: json

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