3.21. /api/v2/payout-form

Введение

Оплата по форме инициируется через запрос методом HTTPS POST на указанный ниже URL с использованием указанных параметров. Для аутентификации запроса используется OAuth HMAC-SHA1. См. Статусы транзакций.

API URL

Примечание

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

Интеграционная среда

Производственная среда

https://sandbox.sbctech.ru/paynet/api/v2/payout-form/ENDPOINTID

https://gate.sbctech.ru/paynet/api/v2/payout-form/ENDPOINTID

https://sandbox.sbctech.ru/paynet/api/v2/payout-form/group/ENDPOINTIDGROUPID

https://gate.sbctech.ru/paynet/api/v2/payout-form/group/ENDPOINTGROUPID

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

Примечание

Запрос должен иметь content-type=application/x-www-form-urlencoded и Заголовки авторизации.
Уточните у менеджера поддержки, требуются ли условные поля для интеграции.

Название параметра

Описание

Значение

client_orderid

Идентификатор заказа, присвоенный Присоединяющейся Стороной.
Необходимость: Обязательно
Тип: String
Длина: 128

amount

Сумма к оплате. Сумма должна быть указана в максимальных единицах с «.» разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек.
Необходимость: Обязательно
Тип: Numeric
Длина: 10

currency

Валюта, в которой проводится операция (трёхбуквенные алфавитные коды валют). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля.
Необходимость: Обязательно
Тип: String
Длина: 3

order_desc

Описание заказа.
Необходимость: Обязательно
Тип: String
Длина: 65K

ipaddress

IP-адрес получателя (IPv4 или IPv6).
Необходимость: Условно
Тип: String
Длина: 7-45

purpose

Назначение Payout.
Необходимость: Условно
Тип: String
Длина: 128

server_callback_url
URL-адрес server_callback_url, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся стороны. Данный параметр может быть передан вместо notify_url. При использовании server_callback_url платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции. При использовании notify_url платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.).
Необходимость: Опционально
Тип: String
Длина: 1024

notify_url
URL-адрес notify_url, по которому будет отправлен обратный вызов с результатом транзакции. Присоединяющаяся сторона может использовать обратные вызовы для индивидуальной обработки завершения транзакции (например, для сбора данных о платежах в информационной системе Присоединяющейся стороны). Список параметров, включенных в обратный вызов, см. в разделе Обратного вызова Присоединяющейся стороны. Данный параметр может быть передан вместо server_callback_url. При использовании notify_url платежный шлюз отправляет уведомление при получении финального статуса и продолжает отправлять уведомления о всех последующих изменениях (возвраты, chargeback и др.). При использовании server_callback_url платежный шлюз отправляет callback-уведомление только при получении финального статуса исходной транзакции.
Необходимость: Опционально
Тип: String
Длина: 1024

redirect_url
URL, на который Получатель перенаправляется после завершения транзакции. Обратите внимание: перенаправление выполняется в любом случае, независимо от того, имеет ли транзакция статус approved, declined или любой другой финальный статус.
Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата «плательщика, параметр может быть использован со значением https://doc.sbctech.ru/. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.
Необходимость: требуется, если отсутствуют оба параметра redirect_success_url и redirect_fail_url
Тип: String
Длина: 1024

redirect_success_url
URL, на который Получатель перенаправляется, когда статус транзакции — approved (см. список статусов).
Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата плательщика, параметр может быть использован со значением http://https://doc.sbctech.ru/. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.
Необходимость: требуется, если отсутствует параметр redirect_url
Тип: String
Длина: 1024

redirect_fail_url
URL, на который Получатель перенаправляется, когда статус транзакции не approved (см. список статусов).
Присоединяющаяся сторона не должна использовать параметры, передаваемые вместе с перенаправленным HTTP-запросом, для определения статуса транзакции. Вместо этого Присоединяющаяся сторона может использовать server_callback_url или команду API статуса. Передайте https://doc.sbctech.ru/, если используется схема обработки транзакций без 3DS и не требуется перенаправлять получателя. Используйте комбинацию redirect_fail_url и redirect_success_url либо redirect_url, но не оба варианта.
Необходимость: требуется, если отсутствует параметр redirect_url
Тип: String
Длина: 1024

account_number

Account номер.
Необходимость: Условно
Тип: String
Длина: 32

account_name

Банковский счет
Необходимость: Условно
Тип: String
Length: 512

ewallet_wallet

Идентификатор e-wallet.
Необходимость: Условно
Тип: String
Длина: 128

crypto_wallet_address

Адрес криптокошелька.
Необходимость: Условно
Тип: String
Длина: 64

bank_name

Имя банка.
Необходимость: Условно
Тип: String
Length: 512

bank_branch

Имя банковского отделения.
Необходимость: Условно
Тип: String
Length: 512

bank_code

Код банка.
Необходимость: Условно
Тип: String
Длина: 32

bank_address1

Адрес банка.
Необходимость: Условно
Тип: String
Длина: 255

bank_zip_code

Почтовый индекс банка.
Необходимость: Условно
Тип: String
Длина: 32

bank_province

Штат банка.
Необходимость: Условно
Тип: String
Длина: 128

bank_area

Область банка
Необходимость: Условно
Тип: String
Длина: 128

bank_city

Город банка.
Необходимость: Условно
Тип: String
Длина: 128

routing_number

Номер маршрута, используется для определения отдела банка в Китае.
Необходимость: Условно
Тип: String
Длина: 32

legal_person_name

Имя на юридическом документе.
Необходимость: Условно
Тип: String
Длина: 128

legal_person_document_number

Номер юридического документа
Необходимость: Условно
Тип: String
Длина: 128

receiver_first_name

Имя Получателя, так же можно отправить как first_name.
Необходимость: Условно
Тип: String
Длина: 128

receiver_last_name

Фамилия Получателя, так же можно отправить как last_name.
Необходимость: Условно
Тип: String
Длина: 128

receiver_birthday

Дата рождения получателя, так-же можно отправить как birthday.
Необходимость: Условно
Тип: Numeric
Длина: 30

receiver_country_code

Код страны Получателя, также можно отправить как country.
Необходимость: Условно
Тип: String
Длина: 3

receiver_state

Штат Получателя, обязательный параметр для стран, которые делятся на штаты (США, Канада, Австралия), также можно отправить как state.
Необходимость: Условно
Тип: String
Длина: 4

receiver_city

Город Получателя, также можно отправить как city.
Необходимость: Условно
Тип: String
Длина: 128

receiver_zip_code

Почтовый индекс Получателя, также можно отправить как zip_code.
Необходимость: Условно
Тип: Numeric
Длина: 32

receiver_address1

Адрес Получателя, также можно отправить как address1.
Необходимость: Условно
Тип: String
Длина: 255

receiver_phone

Номер телефона Получателя, также можно отправить как phone.
Необходимость: Условно
Тип: Numeric
Длина: 128

receiver_email

Адрес электронной почты Получателя, также можно отправить как email.
Необходимость: Условно
Тип: String
Длина: 128

receiver_identity_document_id

Идентификатор удостоверения личности получателя, так-же можно отправитькак identity_document_id.
Необходимость: Условно
Тип: String
Длина: 128

receiver_identity_document_number

Номер удостоверения личности получателя, так-же можно отправитькак identity_document_number.
Необходимость: Условно
Тип: String
Длина: 128

order_desc

Любая дополнительная информация для этой транзакции, которая может быть полезна во внешних системах Присоединяющейся стороны, например VIP-клиент, лид промокампании TV. Будет возвращена в ответе Status и Callback Присоединяющейся стороны.
Необходимость: Опционально
Тип: String
Length: 65k

merchant_form_data

Параметры, отправленные в параметре API merchant_form_data, разбираются в макросы с тем же именем; параметр кодируется в URL, например: testparam%3Dtest1%26mynewparam%3Dtest2, и разбирается в макросы формы $MFD_testparam = test1 и $MFD_mynewparam = test2. Символы имени параметра [a-zA-Z0-9], символы значения [a-zA-Z0-9], управляющие символы [=&], максимальный размер 2 МБ. Например, параметр можно использовать для отображения платёжной формы в светлом/тёмном режиме в зависимости от значения Присоединяющейся стороны (например, передайте в запросе merchant_form_data=theme%3Ddark, и заполнитель макроса $MFD_theme в платёжной форме изменится на dark).
Необходимость: Опционально
Тип: String
Длина: 2M

preferred_language

Предпочтительный язык.
Необходимость: Опционально
Тип: String
Длина: 2

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

Примечание

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

Название параметра

Описание

type

Тип ответа. Может принимать такие значения как: async-response, validation-error, error и т.д. Если тип ответа validation-error или error, параметры error-message и error-code будут содержать детали ошибки.

paynet-order-id

Идентификатор заказа, присвоенный SBC.

merchant-order-id

Идентификатор заказа Присоединяющейся Стороны.

serial-number

Уникальный номер, присваиваемый сервером SBC конкретному запросу от Присоединяющейся стороны.

error-message

Для транзакций в статусе error этот параметр будет содержать причину отклонения или сведения об ошибке.

error-code

Код ошибки для транзакций в статусе error.

redirect_url

URL страницы, на которую Присоединяющаяся сторона должна перенаправить браузер клиента. Присоединяющаяся сторона должна отправить перенаправление HTTP 302.

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

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
&currency=USD
&oauth_consumer_key=merchantlogin
&oauth_nonce=T5v7kcMBsgi
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1753337681
&oauth_version=1.0

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

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

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

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 в зависимости от значения account_number, переданного в запросе Payout.

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

  • account_number = 1234567890 для получения APPROVED

  • account_number = 0987654321 для получения DECLINED

  • account_number = 1987654321 для получения PROCESSOR_INTERNAL_ERROR

Open API Collection

Open this method in the OpenAPI Reference

View in OpenAPI

Коллекция Postman

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

HTTP method
URL

Use /v2/payout-form/ in URL for Payout Form integration

parameters
version
consumer key
consumer secret
timestamp
nonce
signature method

normalized parameters
signature base string
signature
authorization header