.. meta::
   :description: /api/v4/withdrawal-sbp API endpoint Payneteasy: выплата через российскую SBP с использованием номера телефона получателя в качестве идентификатора, альтернатива выплатам на карту.

.. _/api/v4/payout/sbp:

/api/v4/withdrawal-sbp
##############################################


.. role:: ex

.. role:: code

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

Чтобы выполнить выплату, отправьте запрос :code:`HTTPS POST`, используя указанные ниже :ref:`URL-адреса<payout/apis/sbp>` и :ref:`параметры<payout_parameters_sbp>`. Для аутентификации используйте :ref:`RSA-SHA256`.

.. _payout/apis/sbp:

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

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

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

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


.. _payout_parameters_sbp:

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

.. 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:`receiver_phone`
    - Номер телефона Получателя, также можно отправить как :code:`phone`.
    - | ``Необходимость``: Обязательно
      | ``Тип``: Numeric
      | ``Длина``: 128
  * - :code:`order_desc`
    - Любая дополнительная информация об этой транзакции, которая может быть полезна во внешних системах Присоединяющейся стороны, например :ex:`VIP customer`, :ex:`TV promo campaign lead`. Будет возвращена в ответе Status и Callback Присоединяющейся стороны. Для SBP этот параметр используется для передачи кода банка Получателя. За подробностями обратитесь в Payneteasy.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 64k
  * - :code:`bank_id`
    - Любая дополнительная информация для этой транзакции, которая может быть полезна во внешних системах Присоединяющейся стороны, например :ex:`VIP customer`, :ex:`TV promo campaign lead`. Возвращается в ответе Status и Callback Присоединяющейся стороны. Для SBP этот параметр используется для передачи кода банка получателя. Также может быть отправлен как merchant_data. Для получения подробностей обратитесь в Payneteasy.
    - | ``Необходимость``: Обязательно
      | ``Тип``: String
      | ``Длина``: 64k
  * - :code:`ipaddress`
    - IP-адрес получателя (IPv4 или IPv6)
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 7-45
  * - :code:`purpose`
    - Назначение вывода средств.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_first_name`
    - Имя Получателя, так же можно отправить как :code:`first_name`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`receiver_last_name`
    - Фамилия Получателя, так же можно отправить как :code:`last_name`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :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_email`
    - Адрес электронной почты Получателя, также можно отправить как :code:`email`.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`order_desc`
    - Описание заказа.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 64
  * - :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

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


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

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

.. list-table::
  :widths: 30, 70
  :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:: http

  POST /paynet/api/v4/withdrawal-sbp/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

  amount: 100.00
  &client_orderid=123456
  &currency=RUB
  &merchant_data=100000000111
  &order_desc=Test Order Описание
  &phone=89031234567
  &ipaddress=127.0.0.1
  &server_callback_url=https://httpstat.us/200


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

.. code-block:: http

  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:: http

  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.html

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

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

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