.. meta::
   :description: /api/v4/payout-check API endpoint Payneteasy: первый шаг двухэтапного процесса выплаты — предварительная проверка карты получателя и суммы перед вызовом payout-pay.

.. _/api/v4/payout-check/:

/api/v4/payout-check
##############################

.. role:: ex

.. role:: code

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

Выплата инициируется через зарос :code:`HTTPS POST` на указанный ниже :ref:`Ссылки<payout-check/apis>` с использованием указанных :ref:`параметров<payout-check_parameters>` в зависимости от типа выплаты. Для аутентификации запроса используется :ref:`RSA-SHA256`

.. _payout-check/apis:

API URL
^^^^^^^^^^^^^^^^^^^^

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

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

  * - Интеграционная среда
    - Производственная среда
  * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v4/payout-check/ENDPOINTID`
    - :ex:`https://gate.payneteasy.ru/paynet/api/v4/payout-check/ENDPOINTID`
  * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v4/payout-check/group/ENDPOINTGROUPID`
    - :ex:`https://gate.payneteasy.ru/paynet/api/v4/payout-check/group/ENDPOINTGROUPID`


.. _payout-check_parameters:

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

.. note::
  | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации<RSA-SHA256>`.

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

  * - Название параметра
    - Описание
    - Значение
  * - :code:`client_orderid`
    - Идентификатор заказа, присвоенный Присоединяющейся Стороной.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`amount`
    - Сумма к оплате. Сумма должна быть указана в максимальных единицах с "." разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек.
    - | ``Необходимость``: Обязательно
      | ``Тип``: Numeric
      | ``Длина``: 10
  * - :code:`currency`
    - Валюта, в которой проводится операция (трёхбуквенные алфавитные коды валют). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 3
  * - :code:`order_desc`
    - Описание заказа.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 64
  * - :code:`ipaddress`
    - IP-адрес получателя (IPv4 или IPv6)
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 7-45
  * - :code:`purpose`
    - Назначение платежа.
    - | ``Необходимость``: Условно
      | ``Тип``: 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
      | ``Длина``: 128
  * - :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
      | ``Длина``: 128
  * - :code:`redirect_url`
    - | URL, where the Receiver 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` 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 Receiver anywhere. Use either :ex:`redirect_url` or combination of :ex:`redirect_success_url` and :ex:`redirect_fail_url`, not both.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`redirect_success_url`
    - | URL, на который Получатель перенаправляется, когда статус транзакции — :ex:`approved` (см. :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 Receiver 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:`approved` (см. :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://doc.payneteasy.ru` if there is no need to redirect Receiver anywhere. Use either combination of :ex:`redirect_fail_url` and :ex:`redirect_success_url` or :ex:`redirect_url`, not both.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 1024
  * - :code:`credit_card_number`
    - Номер банковской карты клиента. **Примечание: Для сценария оплаты на карту внутри системы, эта карта рассматривается как источник, и к ней будут относиться все процессинговые ограничения, списки и проверки мошенничества.**
    - | ``Необходимость``: Условно
      | ``Тип``: Numeric
      | ``Длина``: 20
  * - :code:`card_printed_name`
    - Имя владельца карты, напечатанное на банковской карте.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`expire_month`
    - Месяц окончания срока действия банковской карты.
    - | ``Необходимость``: Условно
      | ``Тип``: Numeric
      | ``Длина``: 2
  * - :code:`expire_year`
    - Год окончания срока действия банковской карты.
    - | ``Необходимость``: Условно
      | ``Тип``: Numeric
      | ``Длина``: 4
  * - :code:`cvv2`
    - CVV2-код Плательщика. CVV2 (Card Verification Значение) — это трех- или четырех-значное число ПОСЛЕ номера кредитной карты в области подписи карты.
    - | ``Необходимость``: Условно
      | ``Тип``: Numeric
      | ``Длина``: 3-4
  * - :code:`account_number`
    - Номер банковского счета
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 32
  * - :code:`account_name`
    - Банковский счет
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`ewallet_type`
    - Тип e-wallet.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 64
  * - :code:`ewallet_wallet`
    - Идентификатор e-wallet.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`crypto_wallet_address`
    - Адрес криптокошелька.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 64
  * - :code:`bank_name`
    - Имя банка.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 255
  * - :code:`bank_branch`
    - Имя банковского отделения.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 255
  * - :code:`bank_code`
    - Код банка.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 32
  * - :code:`bank_city`
    - Город банка.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`bank_address1`
    - Адрес банка.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 255
  * - :code:`bank_zip_code`
    - Почтовый индекс банка.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 255
  * - :code:`bank_province`
    - Штат банка.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 255
  * - :code:`bank_area`
    - Область банка
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 255
  * - :code:`routing_number`
    - Номер маршрута, используется для определения отдела банка в Китае.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 16
  * - :code:`legal_person_name`
    - Имя на юридическом документе.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`legal_person_document_number`
    - Номер юридического документа
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_first_name`
    - Имя Получателя, так же можно отправить как :code:`first_name`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_last_name`
    - Фамилия Получателя, так же можно отправить как :code:`last_name`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_middle_name`
    - Отчество получателя, так-же можно отправить как :code:`middle_name`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_birthday`
    - Дата рождения получателя, так-же можно отправить как :code:`birthday`.
    - | ``Необходимость``: Условно
      | ``Тип``: Numeric
      | ``Длина``: 30
  * - :code:`receiver_country_code`
    - Код страны Получателя, также можно отправить как :code:`country`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 3
  * - :code:`receiver_state`
    - Штат Получателя, обязательный параметр для стран, которые делятся на штаты (США, Канада, Австралия), также можно отправить как :code:`state`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 4
  * - :code:`receiver_city`
    - Город Получателя, также можно отправить как :code:`city`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_zip_code`
    - Почтовый индекс Получателя, также можно отправить как :code:`zip_code`.
    - | ``Необходимость``: Условно
      | ``Тип``: Numeric
      | ``Длина``: 32
  * - :code:`receiver_address1`
    - Адрес Получателя, также можно отправить как :code:`address1`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 256
  * - :code:`receiver_phone`
    - Номер телефона Получателя, также можно отправить как :code:`phone`.
    - | ``Необходимость``: Условно
      | ``Тип``: Numeric
      | ``Длина``: 128
  * - :code:`receiver_email`
    - Адрес электронной почты Получателя, также можно отправить как :code:`email`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_identity_document_id`
    - Идентификатор удостоверения личности получателя, так-же можно отправитькак :code:`identity_document_id`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_identity_document_number`
    - Номер удостоверения личности получателя, так-же можно отправитькак :code:`identity_document_number`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`order_desc`
    - Любая дополнительная информация о транзакции, которая может быть полезна во внешних системах Присоединяющейся стороны, например :ex:`VIP клиент`, :ex:`лид промокампании на ТВ`.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 64k
  * - :code:`bank_bic`
    - BIC-код банка получателя
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_inn`
    - Уникальный идентификатор для налогообложения получателя
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`customer_level`
    - Уровень клиента в системе CMS.
    - | ``Необходимость``: Опционально
      | ``Тип``: Varchar
      | ``Длина``: 32
  * - :code:`customer_id`
    - Идентификатор клиента в системе CMS. Параметр становится обязательным, если включена система CMS в режиме определения клиента Платёжным шлюзом.
    - | ``Необходимость``: Опционально
      | ``Тип``: Int
      | ``Длина``: 10
  * - :code:`merchant_customer_identifier`
    - Идентификатор клиента-продавца в системе CMS. Параметр становится обязательным, если включена система CMS в режиме CRM.
    - | ``Необходимость``: Опционально
      | ``Тип``: Varchar
      | ``Длина``: 64
  * - :code:`card_recurring_payment_id`
    - Токенизированный идентификатор владельца карты. Нужно отправлять или параметр :code:`card_recurring_payment_id` или комбинацию из :code:`credit_card_number`, :code:`card_printed_name`, :code:`expire_month` и :code:`expire_year`, но не все в одном запросе. Для создания :code:`card_recurring_payment_id` см. :ref:`api-v4-card-ref-id`. **Примечание: ля сценария оплаты на карту внутри системы, эта карта рассматривается как источник, и к ней будут относиться все процессинговые ограничения, списки и проверки мошенничества.**
    - | ``Необходимость``: Условно
      | ``Тип``: Long
  * - :code:`recurring-payment-id`
    - Recurring Payment ID может быть передан вместо данных держателя карты. Для нативных транзакций CVV не требуется. Обновление данных клиента возможно через :ref:`/api/v4/update-recurring-payment/<api_v4_update-recurring-payment>`. Процесс создания Recurring Payment ID инициируется :code:`HTTPS POST` запросом с использованием указанных ниже :ref:`URLs<api_v4_card-ref-id_request_url>` и :ref:`параметров<v4_card-ref-id_request_parameters>`. Используйте :ref:`RSA-SHA256` для аутентификации
    - | ``Необходимость``: Условно
      | ``Тип``: Long

\* Спросите менеджера службы поддержки если условные параметры обязательны для интеграции

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

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

.. list-table::
  :widths: 35, 65
  :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:`error-message`
    - Для транзакций в статусе :ex:`error` этот параметр будет содержать причину отклонения или сведения об ошибке.
  * - :code:`error-code`
    - Код ошибки для транзакций в статусе :ex:`error`.

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

.. code-block:: guess

  POST /paynet/api/v4/payout-check/39915 HTTP/1.1
  Host: sandbox.payneteasy.ru
  User-Agent: curl/7.83.0
  Accept: */*
  Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="b5E31Tw6SVjauE29uOf2jOLnuUSXmVdE", oauth_signature="WrW79JHNUVwDRhCGWQYgaN6xmJXpQxy8XSNyCOL6b2Wyf7V5BWGMe2TZa1bjC9ZeO0Q3FcQxeGGHv0%2F7hsMAsJNQEET321VNsbDwao2Ep%2Bp7eoYiGYrVveSrSW1diCrBf3AJYJZM0PTJ67Sl8XyeTVBHT4kpC5qBu3xDQ3aFfKnmRTmn9fiVsYsYu3DQrsHM1K9uAoltGt3Muz0kCDZ3MWNGrNqtdpWuar8HRQD3kckcPjuN9D6VrSuQm9eLx27G%2FvkiP%2BZ44i8ghIUp61NWSrJ4Ky69JiZ%2FoaVVmUTEaanc%2F%2B%2BQT6jBwWy%2Bb%2FTLUrxtSakeNfcjn1JVwRf4aCX2fhyG5ozH%2BjiXF6eRb83WVqBUAwykSq35pLU3Vmua3pKMKAJK1ZRDZdjGrT50KJg5tBniC4JFzdQqjQf%2FhFnDYodfIK3S2qZo%2FD3Bmlya46iEcK6SAQdNBBQue3E5Qi8FEHYrY1o7K8wDyzT1QzqqHF%2BQdmXcElSGu9ge0Y655%2BbGtXhnsUWnKEO0NGqErvAwzm7yUg0e5QWHVf505aE7pr5K4z%2Fzj7AvkuD7R1savqam%2BnnuSfq1E%2BnnnN7mTcC0g18Sr38vdTshcGq99YW3xWKc%2FpuooZYdYa5A6u46o%2BREZSTCD2XexcV49%2F9eVn3xdoTXYq4NISJSY8U7ThKnr0g%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1677831012", oauth_version="1.0"
  Content-Length: 150
  Content-Type: application/x-www-form-urlencoded
  Connection: close

  account_name=1234
  &account_number=1234
  &amount=10.42
  &client_orderid=1
  &currency=USD
  &routing_number=15
  &server_callback_url=https%3A%2F%2Fhttpstat.us%2F200


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

.. code-block:: javascript

  HTTP/1.1 200
  Server: server
  Date: Fri, 03 Mar 2023 08:10:34 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: 137

  type=async-response
  &serial-number=00000000-0000-0000-0000-000002e2c322
  &merchant-order-id=1
  &paynet-order-id=6982864
  &end-point-id=39915

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

.. code-block:: guess

  HTTP/1.1 403 Forbidden
  Server: server
  Date: Thu, 25 Aug 2022 06:50:16 GMT
  Content-Type: text/html
  Content-Length: 735
  Connection: close
  X-XSS-Protection: 1
  X-Content-Type-Options: nosniff
  Strict-Transport-Security: max-age=31536000

  <!DOCTYPE html>
  <html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>403</title>

  <style type="text/css">
  body {
  font-family: Arial, sans-serif;
  font-size: 130%;
  background-color: #eee;
  }

  p {
  margin: 10em auto 0;
  width: 500px;
  border: 1px solid gray;
  text-align: center;
  vertical-align: middle;
  padding: 40px 20px;
  background-color: #fff;
  -webkit-border-radius: 20px;
  -moz-border-radius: 20px;
  border-radius: 20px;
  }
  </style>
  </head>

  <body>
  <p>Access is denied</p>
  </body>
  </html>


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

.. raw:: html
    :file: ../_static/Postman/Postman_payout_with_two_stages.html

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

Вставьте приватный ключ PKCS#1 PEM для среды sandbox в поле ниже. Конструктор запросов поддерживает длину ключа до 4096.

.. raw:: html
    :file: ../_static/examples/V4Payout-check_Debug.html