.. meta::
   :description: /api/v4/payout-form API endpoint SBC: инициирует выплату через размещённую форму, в которой получатель вводит данные карты для получения средств.

.. _/api/v4/payout/form/:

/api/v4/payout-form
####################

.. role:: ex

.. role:: code

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

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

.. _payout-form/apis:

API URL
^^^^^^^^

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

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

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

.. _payout_form_parameters:

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

.. note::
  | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации<RSA-SHA256>`.
  | Ask Support Менеджер if Conditional fields are Обязательный for integration.

.. 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`
    - Назначение Payout.
    - | ``Необходимость``: Условно
      | ``Тип``: 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:`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.sbctech.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
      | ``Длина``: 1024
  * - :code:`redirect_succes_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.sbctech.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.sbctech.ru` if you use non-3DS schema for transactions processing and you have no need to return Receiver anywhere. Use either combination of :ex:`redirect_fail_url` and :ex:`redirect_success_url` or :ex:`redirect_url`, not both.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 1024
  * - :code:`account_number`
    - Account номер.
    - | ``Необходимость``: Условно
      | ``Тип``: String
      | ``Длина``: 24
  * - :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_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_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:`лид промокампании TV`. Будет возвращена в ответе Status и Callback Присоединяющейся стороны.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 64k
  * - :code:`merchant_form_data`
    - Параметры, отправленные в параметре API merchant_form_data, разбираются в макросы с тем же именем; параметр кодируется в URL, например: :ex:`testparam%3Dtest1%26mynewparam%3Dtest2`, и разбирается в макросы формы :ex:`$MFD_testparam = test1` и :ex:`$MFD_mynewparam = test2`. Символы имени параметра [a-zA-Z0-9], символы значения [a-zA-Z0-9], управляющие символы [=&], максимальный размер 2 МБ. Например, параметр можно использовать для отображения платёжной формы в светлом/тёмном режиме в зависимости от значения Присоединяющейся стороны (например, передайте в запросе :code:`merchant_form_data=theme%3Ddark`, и заполнитель макроса :ex:`$MFD_theme` в платёжной форме изменится на :ex:`dark`).
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 128
  * - :code:`preferred_language`
    - Предпочтительный язык.
    - | ``Необходимость``: Опционально
      | ``Тип``: String
      | ``Длина``: 2
  * - :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

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

.. 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`
    - Идентификатор заказа, присвоенный SBC.
  * - :code:`merchant-order-id`
    - Идентификатор заказа Присоединяющейся Стороны.
  * - :code:`serial-number`
    - Уникальный номер, присваиваемый сервером SBC конкретному запросу от Присоединяющейся стороны.
  * - :code:`error-message`
    - Для транзакций в статусе :ex:`error` этот параметр будет содержать причину отклонения или сведения об ошибке.
  * - :code:`error-code`
    - Код ошибки для транзакций в статусе :ex:`error`.
  * - :code:`redirect_url`
    - URL страницы, на которую Присоединяющаяся сторона должна перенаправить браузер клиента. Присоединяющаяся сторона должна отправить перенаправление :ex:`HTTP 302`.

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

.. code-block:: http


    POST /paynet/api/v4/payout-form/39915 HTTP/1.1
    Host: sandbox.sbctech.ru
    User-Agent: curl/7.83.0
    Accept: */*
    Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="GtAAIvMXjF6QLjWDaFk8L9C4glV9rwQ0", oauth_signature="RpPfm4BDtjrDikqy3hvQIUiLdWOM4Gao0VzSkFIbvEI1RSK969crOUmNHXFNXgoNKV7yvI98jlTar3IZPin%2B8JwXRN0EgS8SUQHd1xPQaKD6RdLXazrwNUaxl0yeg9IwRLBJz5TzF7DphCQVwTvKZkSYfFnLayQyheExhzSJPCFUm%2Bh33PtxJAAsCscYgTGlNkaVRYARZ5b2Pe%2FSygITeg2xevn0yjoqd1Rl0wbB3d1EvqGB7AFJMxpMG1lMe33w6FKvU%2B6rJgIGEipkoTZ8HITwZybZvhrFDWst1ODTzJxfuxd8JBE0Pn1dwDBAbLkPKqD5%2F%2BLOsszUnDJ%2FJSAItNWMmEQ7QBumvYG2qgUSKJi%2FsG7VM%2FJY1esr5CELW%2FeMXfWEwNMNx0w%2BUQ8t%2F7YOWQpZAmtfykRyM%2BNwGbHaFWt%2F6honcfXtwbYIOu5XtWyiOn37CxdY5CB9sZyo%2FAFP7isByhs3kRpcc%2BioFlpsyXWi1K3LvevqheGC8jDsf6XTqh%2Fn%2B1njjopUmkuKFB1qzxu0I%2FO4AIIPzm%2BvSfJmTzO5iYV11%2FtFzLEr9BCVRXShbjACwRFEDEQv9C73csGpWop9XGB7CKLaPD3KlLswVNMuOhZyU4FxLP%2BglEpJ7xJB45arMHShBHUl1GnedAHh7Nq46Si1mEOBpm0rdEUgRJfZbGKu12VO2U9B5q8Nack3QNHD9yJ3hyEEaURGg2yzSaCiTJd2wuOmqJ4KJ9aZTQ0F6T6wHj9lf0dzE47KK3ldbqryGUNwTBvQRPJqPgEfIQy6Ou3hbimi1feWQoA9Q9vx7SNPiKaZMYG8tNLo6qMT00iZ12b3qgbiVNbFYrqWckQrEoOj16Lp9A%2FeaMkF%2FFL%2B6DxicGPQaPTMezTRnHTvkI4rZcRZoxlOcEeI3a%2FWTiBXxcUVwfnpOaWeOi4DWdSY%2BJuiIIGRjBjh5owtR87lexWAxUPH8a5bmrS9TcHNF1amggunLjzk5hDAiMgJRyhL7btB2B3rkHbNvbfZ6QnNAjvgBWdoB7djjbRe4Pob4T3wC%2Bg5aTFxhyQSEIlhKiQ9WpPUlUR3stXyP31zgs4BgCbi3t1OYyV2XCl0W%2BrXa5x%2FqFbfN3AJB7ttfq4TNi5G0CeabcZ0T%2FhlHn2sopQPkX1ZnokmO3Tof7TANmZ9nM0avlTjFJjOpqunPoc7Uq4VbT7QyTayfO9d38IizWEncc77f6ZiDxnUQW0jJhrt0e4GN2iJ7WwcZ82NSq5kQAPGUaqiUsr5YchSZke7KUXuJjKVqLpVI7VyR%2B82LcA2oqVeu6ifgjGuCJBQiC%2F9nsEetosRz8Z2vp1jiZ%2F3u61n0dwkowGftGcnIT73JFr7hg%3D%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1678178824", oauth_version="1.0"
    Content-Length: 381
    Content-Type: application/x-www-form-urlencoded
    Connection: close


    account_number=1234567890
    &amount=100
    &bank_branch=test_branch
    &bank_name=test_bank
    &client_orderid=12345
    &currency=USD
    &order_desc=TEST
    &redirect_url=http%3A%2F%2Fhttps://doc.sbctech.ru%2Fdoc%2Fdummy.htm%09
    &server_callback_url=https%3A%2F%2Fhttpstat.us%2F200


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

.. code-block:: http

  HTTP/1.1 200
  Server: server
  Date: Tue, 07 Mar 2023 08:47:54 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: 281

  type=async-form-response
  &serial-number=00000000-0000-0000-0000-000002e33afd
  &merchant-order-id=12345
  &paynet-order-id=6993513
  &redirect-url=https%3A%2F%2Fsandbox.sbctech.ru%2Fpaynet%2Fform%2Finit%2FBB587546567A31587163597A684535634A775969614A5A6367507733385468565A54514E48467135715A74773D

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

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

Test Scenario
^^^^^^^^^^^^^

Разные статусы транзакций Payout могут быть получены в песочнице в зависимости от значения :code:`account_number`, переданного в запросе Payout.

Тестовые значения :ex:`account_number`:

    * :ex:`account_number` = 1234567890 для получения APPROVED
    * :ex:`account_number` = 0987654321 для получения DECLINED
    * :ex:`account_number` = 1987654321 для получения PROCESSOR_INTERNAL_ERROR

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

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

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

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

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