.. meta::
   :description: /api/v2/auth-cash API endpoint Payneteasy: авторизует транзакцию внесения наличных с деталями о вносителе и сумме через API.

.. _/api/v2/auth-cash/:

/api/v2/auth-cash
##################

.. role:: ex

.. role:: code

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

Auth-cash инициируется запросом :code:`HTTPS POST` с использованием указанных ниже :ref:`URL<api_v2_auth-cash_url>` и :ref:`параметров<api_v2_auth-cash_request_parameters_url>`. Для аутентификации используйте :ref:`SHA-1<SHA1>`. См. :ref:`статусы<statuses>`.

.. _api_v2_auth-cash_url:

API URL
^^^^^^^^

.. note::
    | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее.

.. list-table::
   :widths: 50, 50
   :header-rows: 1
   :class: longtable

   * - Интеграционная среда
     - Производственная среда
   * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/auth-cash/ENDPOINTID`
     - :ex:`https://gate.payneteasy.ru/paynet/api/v2/auth-cash/ENDPOINTID`

.. _api_v2_auth-cash_request_parameters_url:

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

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

  * - Название параметра
    - Описание
    - Значение
  * - :code:`client_orderid`
    - Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`order_desc`
    - Описание заказа.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 64k
  * - :code:`amount`
    - Сумма к оплате. Сумма должна быть указана в наибольших единицах с разделителем :ex:`.`. Например, :ex:`10.5` для USD означает 10 долларов США и 50 центов.
    - | ``Необходимость``: Обязательно
      | ``Тип``: Numeric
      | ``Длина``: 10
  * - :code:`currency`
    - Валюта, в которой проводится операция (см. :ref:`Коды валют<currency_codes>`). Примеры значений: :ex:`USD` для доллара США, :ex:`EUR` для европейского евро, RUB для российского рубля.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 3
  * - :code:`address1`
    - Адрес Плательщика, строка 1. (Обратите внимание, что в некоторых случаях невозможно отправить адрес длиной более 50 символов. Для получения более подробной информации обратитесь к вашему менеджеру.)
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 256
  * - :code:`city`
    - Город Плательщика.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 50
  * - :code:`zip_code`
    - Почтовый индекс Плательщика.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 10
  * - :code:`country`
    - Страна Плательщика. Для списка действительных кодов см. :ref:`Коды стран<country_codes>`.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 2
  * - :code:`phone`
    - Полный международный номер телефона Плательщика, включая код страны.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 15
  * - :code:`email`
    - Адрес электронной почты Плательщика.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 50
  * - :code:`ipaddress`
    - IP-адрес Плательщика, передаётся для целей мониторинга мошенничества.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 45
  * - :code:`control`
    - | Контрольная сумма, сгенерированная :ref:`SHA-1<SHA1>`. Строка для подписи представляет собой объединение следующих параметров:
      | 1. :ex:`<ENDPOINTID | ENDPOINTGROUPID>` (См.: :ref:`URL запроса<api_v2_preauth-form_url>`).
      | 2. Параметр запроса::ex:`client_orderid`.
      | 3. Параметр запроса: :ex:`amount` (в младших единицах).
      | 4. Параметр запроса: :ex:`email`,
      | 5. :ex:`merchant_control` (Контрольный ключ, назначенный для учетной записи Присоединяющейся стороны в Payneteasy).
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 40
  * - :code:`first_name`
    - Имя Плательщика.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 50
  * - :code:`last_name`
    - Фамилия Плательщика.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 50
  * - :code:`state`
    - Штат плательщика (двухбуквенный код штата). Список допустимых кодов штатов см. в :ref:`обязательных кодах штатов<mandatory_state_codes_url>`. Требуется для США, Канады и Австралии.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 2
  * - :code:`redirect_url`
    - | URL, where the Payer is redirected to upon completion of the transaction.
        Please note that redirection is performed in any case, no matter whether transaction is :ex:`approved`, :ex:`declined` or in any other final :ref:`status<statuses>`.
      | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction.
        Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command</api/v2/status/>`.
        Pass :ex:`https://doc.payneteasy.ru` if you have no need to return payer anywhere. Use either :ex:`redirect_url` or combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url`, not both.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 1024
  * - :code:`redirect_success_url`
    - | URL-адрес, на который будет перенаправлен Плательщик после получения :ex:`успешного` статуса транзакции (см. :ref:`Статусы транзакций<statuses>`).
      | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction.
        Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command</api/v2/status/>`.
        Otherwise put :ex:`https://doc.payneteasy.ru` if there is no need to redirect Payer anywhere. Use either combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url` or :ex:`redirect_url`, not both.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 1024
  * - :code:`redirect_fail_url`
    - | URL-адрес, на который будет перенаправлен Плательщик после получения :ex:`неуспешного` статуса транзакции (см. :ref:`Статусы транзакций<statuses>`).
      | Connecting Party must not use the parameters come along with the redirect HTTP Request to treat the status of the transaction.
        Instead Connecting Party can utilize :ex:`server_callback_url` or :ref:`status API command</api/v2/status/>`.
        Pass :ex:`https://doc2.codetime.net` if there is no need to redirect Payer anywhere. Use either combination of :ex:`redirect_fail_url` and :ex:`redirect_success_url` or :ex:`redirect_url`, not both.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 1024
  * - :code:`ssn`
    - Последние четыре цифры номера социального страхования Плательщика.
    - | ``Необходимость``: Опционально
      | ``Тип``: Numeric
      | ``Длина``: 32
  * - :code:`birthday`
    - Дата рождения Плательщика в формате :ex:`YYYYMMDD`.
    - | ``Необходимость``: Опционально
      | ``Тип``: Numeric
      | ``Длина``: 8
  * - :code:`cell_phone`
    - Полный международный мобильный номер телефона Плательщика, включая код страны.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 15
  * - :code:`site_url`
    - URL-адрес сайта электронной коммерции, откуда происходит платеж.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`server_callback_url`
    - | URL-адрес :ex:`server_callback_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны<merchant_callback_parameters>`. Данный параметр может быть передан вместо :ex:`notify_url`. При использовании :ex:`server_callback_url` платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. При использовании :ex:`notify_url` платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.).
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 1024
  * - :code:`notify_url`
    - | URL-адрес :ex:`notify_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны<merchant_callback_parameters>`. Данный параметр может быть передан вместо :ex:`server_callback_url`. При использовании :ex:`notify_url` платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). При использовании :ex:`server_callback_url` платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 1024
  * - :code:`preferred_language`
    - Двухбуквенный код языка плательщика для многоязычных счетов.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 2

.. _api_v2_auth-cash_response_parameters:

Параметры ответа
^^^^^^^^^^^^^^^^^^^

.. note::
  | Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра.

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

   * - Параметры ответа
     - Описание
   * - :code:`type`
     - Тип ответа. Может принимать такие значения как: :ex:`async-response`, :ex:`validation-error`, :ex:`error` и т.д. Если тип ответа :ex:`validation-error` или :ex:`error`, параметры :ex:`error-message` и :ex:`error-code` будут содержать детали ошибки.
   * - :code:`paynet-order-id`
     - Идентификатор заказа, присвоенный Payneteasy.
   * - :code:`merchant-order-id`
     - Идентификатор заказа Присоединяющейся Стороны.
   * - :code:`serial-number`
     - Уникальный номер, присваиваемый сервером Payneteasy конкретному запросу от Присоединяющейся стороны.
   * - :code:`end-point-id`
     - Идентификатор терминала, используемый для транзакции.
   * - :code:`error-message`
     - Для транзакций в статусе :ex:`error` этот параметр будет содержать причину отклонения или сведения об ошибке.
   * - :code:`error-code`
     - Код ошибки для транзакций в статусе :ex:`error`.

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

.. code-block:: guess

    POST /paynet/api/v2/auth-cash/46760 HTTP/1.1
    Host: sandbox.payneteasy.ru
    User-Agent: curl/7.83.0
    Accept: */*
    Content-Length: 592
    Content-Type: application/x-www-form-urlencoded
    Connection: close

    client_orderid=inv3982750
    &order_desc=Test Order Описание
    &first_name=John
    &last_name=Smith
    &ssn=1267
    &birthday=19820115
    &address1=100 Main st
    &city=Seattle&state=WA
    &zip_code=98102
    &country=US
    &phone=+12063582043
    &cell_phone=+19023384543
    &amount=55
    &email=john.smith@gmail.com
    &currency=USD
    &ipaddress=65.153.12.232
    &site_url=https://doc2.codetime.net
    &purpose=user_account1
    &redirect_url=http://sandbox.payneteasy.ru/doc/dummy.htm
    &server_callback_url=https://httpstat.us/200
    &merchant_data=VIP customer
    &control=ce2dcc2b307c123242b9867cb0ce15617b8ee7f9
    &preferred_language=en

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

.. code-block:: none

    HTTP/1.1 200
    Server: server
    Date: Wed, 14 Jun 2023 08:43:52 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: 146

    type=async-response
    &serial-number=00000000-0000-0000-0000-000002eb1adf
    &merchant-order-id=inv3982750
    &paynet-order-id=7174243
    &end-point-id=46760

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

.. code-block:: none

    HTTP/1.1 200
    Server: server
    Date: Wed, 14 Jun 2023 08:43:52 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: 146

    type=validation-error
    &serial-number=00000000-0000-0000-0000-000002ddb0d4
    &error-message=Project+with+currency+RUB+does+not+apply+request+with+currency+USD
    &error-code=16

Коллекция Postman
^^^^^^^^^^^^^^^^^^

.. raw:: html
    :file: ../_static/Postman/Postman_auth-cash.html

Конструктор запросов
^^^^^^^^^^^^^^^

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