.. meta:: :description: /api/v2/payout-form API endpoint Payneteasy: инициирует выплату через размещённую форму, в которой получатель вводит данные карты и получает средства. .. _/api/v2/payout/form/: /api/v2/payout-form #################### .. role:: ex .. role:: code Введение ^^^^^^^^^^^^ Оплата по форме инициируется через запрос методом :code:`HTTPS POST` на указанный ниже :ref:`URL` с использованием указанных :ref:`параметров`. Для аутентификации запроса используется :ref:`OAuth HMAC-SHA1`. См. :ref:`Статусы транзакций`. .. _api_v2_payout_form_url: API URL ^^^^^^^^ .. note:: | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Интеграционная среда - Производственная среда * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/payout-form/ENDPOINTID` - :ex:`https://gate.payneteasy.ru/paynet/api/v2/payout-form/ENDPOINTID` * - :ex:`https://sandbox.payneteasy.ru/paynet/api/v2/payout-form/group/ENDPOINTIDGROUPID` - :ex:`https://gate.payneteasy.ru/paynet/api/v2/payout-form/group/ENDPOINTGROUPID` .. _api_v2_payout_form_parameters: Параметры запроса ^^^^^^^^^^^^^^^^^^ .. note:: | Запрос должен иметь content-type=application/x-www-form-urlencoded и :ref:`Заголовки авторизации`. | Уточните у менеджера поддержки, требуются ли условные поля для интеграции. .. 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 | ``Длина``: 65K * - :code:`ipaddress` - IP-адрес получателя (IPv4 или IPv6). - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 7-45 * - :code:`purpose` - Назначение Payout. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`server_callback_url` - | URL-адрес :ex:`server_callback_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны`. Данный параметр может быть передан вместо :ex:`notify_url`. При использовании :ex:`server_callback_url` платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. При использовании :ex:`notify_url` платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 * - :code:`notify_url` - | URL-адрес :ex:`notify_url`, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе :ref:`Обратного вызова Присоединяющейся стороны`. Данный параметр может быть передан вместо :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`. | 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`. 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. - | ``Необходимость``: требуется, если отсутствуют оба параметра redirect_success_url и redirect_fail_url | ``Тип``: String | ``Длина``: 1024 * - :code:`redirect_success_url` - | URL, на который Получатель перенаправляется, когда статус транзакции — :ex:`approved` (см. :ref:`список статусов`). | 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`. 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. - | ``Необходимость``: требуется, если отсутствует параметр :ex:`redirect_url` | ``Тип``: String | ``Длина``: 1024 * - :code:`redirect_fail_url` - | URL, на который Получатель перенаправляется, когда статус транзакции не :ex:`approved` (см. :ref:`список статусов`). | 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`. Pass :ex:`https://doc.payneteasy.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. - | ``Необходимость``: требуется, если отсутствует параметр :ex:`redirect_url` | ``Тип``: String | ``Длина``: 1024 * - :code:`account_number` - Account номер. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 32 * - :code:`account_name` - Банковский счет - | ``Необходимость``: Условно | ``Тип``: String | ``Length``: 512 * - :code:`ewallet_wallet` - Идентификатор e-wallet. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`crypto_wallet_address` - Адрес криптокошелька. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 64 * - :code:`bank_name` - Имя банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Length``: 512 * - :code:`bank_branch` - Имя банковского отделения. - | ``Необходимость``: Условно | ``Тип``: String | ``Length``: 512 * - :code:`bank_code` - Код банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 32 * - :code:`bank_address1` - Адрес банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 255 * - :code:`bank_zip_code` - Почтовый индекс банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 32 * - :code:`bank_province` - Штат банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`bank_area` - Область банка - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`bank_city` - Город банка. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 128 * - :code:`routing_number` - Номер маршрута, используется для определения отдела банка в Китае. - | ``Необходимость``: Условно | ``Тип``: String | ``Длина``: 32 * - :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 | ``Длина``: 255 * - :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 | ``Length``: 65k * - :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 | ``Длина``: 2M * - :code:`preferred_language` - Предпочтительный язык. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2 Параметры ответа ^^^^^^^^^^^^^^^^^^^ .. 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:`redirect_url` - URL страницы, на которую Присоединяющаяся сторона должна перенаправить браузер клиента. Присоединяющаяся сторона должна отправить перенаправление :ex:`HTTP 302`. Пример запроса ^^^^^^^^^^^^^^^ .. code-block:: guess POST /paynet/api/v2/payout-form/39529 HTTP/1.1 Host: sandbox.doc2.com User-Agent: curl/8.12.1 Accept: */* Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="merchantlogin",oauth_timestamp="1753337681",oauth_nonce="T5v7kcMBsgi",oauth_signature_method="HMAC-SHA1",oauth_signature="wTTQQiN%2F2bGjfCTcSAQ3ZhAHMLw%3D" Content-Length: 249 Content-Type: application/x-www-form-urlencoded Connection: keep-alive account_number=1234567890 &order_desc=Test_Order_Описание &amount=100 &bank_branch=test_branch &bank_name=test_bank &client_orderid=12345 ¤cy=USD &oauth_consumer_key=merchantlogin &oauth_nonce=T5v7kcMBsgi &oauth_signature_method=HMAC-SHA1 &oauth_timestamp=1753337681 &oauth_version=1.0 Пример успешного ответа ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: javascript HTTP/1.1 200 Server: server Date: Thu, 24 Jul 2025 06:45:56 GMT Content-Type: text/html;charset=utf-8 Connection: keep-alive Keep-Alive: timeout=60 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: 142 type=async-response &serial-number=00000000-0000-0000-0000-000002f3b45d &merchant-order-id=12345 &paynet-order-id=7366391 &end-point-id=132490 Пример неуспешного ответа ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: guess HTTP/1.1 403 Server: server Date: Thu, 24 Jul 2025 06:26:23 GMT Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Connection: keep-alive Keep-Alive: timeout=60 X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Length: 102 type=error &serial-number=00000000-0000-0000-0000-000002f3b456 &error-message=Forbidden &error-code=-1 Test Scenario ^^^^^^^^^^^^^ Различные статусы транзакций Payout можно получить в sandbox в зависимости от значения :code:`account_number`, переданного в запросе Payout. Тестовые значения :ex:`account_number`: * :ex:`account_number` = 1234567890 для получения APPROVED * :ex:`account_number` = 0987654321 для получения DECLINED * :ex:`account_number` = 1987654321 для получения PROCESSOR_INTERNAL_ERROR .. only:: openapi_doc_enabled Open API Collection ^^^^^^^^^^^^^^^^^^^ Open this method in the OpenAPI Reference .. raw:: html View in OpenAPI Коллекция Postman ^^^^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/Postman/Postman_payout_form.html Конструктор запросов ^^^^^^^^^^^^^^^ .. raw:: html :file: ../_static/examples/payout_Debug.html