3.34. /api/v4/payout-form

Введение

Чтобы отправить запрос payout-form, отправьте запрос HTTPS POST, используя указанные ниже URL-адреса и параметры. Для аутентификации используйте OAuth RSA-SHA256.

API URL

Примечание

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

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

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

Примечание

Запрос должен иметь content-type=application/x-www-form-urlencoded и Заголовки авторизации.

Ask Support Менеджер if Conditional fields are Обязательный for integration.

Название параметра	Описание	Значение
client_orderid	Идентификатор заказа, присвоенный Присоединяющейся Стороной.	`Необходимость`: Обязательно `Тип`: String `Длина`: 128
amount	Сумма к оплате. Сумма должна быть указана в максимальных единицах с «.» разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек.	`Необходимость`: Обязательно `Тип`: Numeric `Длина`: 10
currency	Валюта, в которой проводится операция (трёхбуквенные алфавитные коды валют). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля.	`Необходимость`: Обязательно `Тип`: String `Длина`: 3
order_desc	Описание заказа.	`Необходимость`: Условно `Тип`: String `Длина`: 64
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, но не и того, и другого одновременно.	`Необходимость`: Опционально `Тип`: String `Длина`: 1024
redirect_succes_url	URL, на который Получатель перенаправляется, когда статус транзакции — approved (см. список статусов). Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата плательщика, параметр может быть использован со значением http://https://doc.sbctech.ru/. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_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, но не оба варианта.	`Необходимость`: Опционально `Тип`: String `Длина`: 1024
account_number	Account номер.	`Необходимость`: Условно `Тип`: String `Длина`: 24
account_name	Банковский счет	`Необходимость`: Условно `Тип`: String `Длина`: 128
ewallet_type	Тип e-wallet.	`Необходимость`: Условно `Тип`: String `Длина`: 64
ewallet_wallet	Идентификатор e-wallet.	`Необходимость`: Условно `Тип`: String `Длина`: 128
crypto_wallet_address	Адрес криптокошелька.	`Необходимость`: Условно `Тип`: String `Длина`: 64
bank_name	Имя банка.	`Необходимость`: Условно `Тип`: String `Длина`: 255
bank_branch	Имя банковского отделения.	`Необходимость`: Условно `Тип`: String `Длина`: 255
bank_code	Код банка.	`Необходимость`: Условно `Тип`: String `Длина`: 32
bank_address1	Адрес банка.	`Необходимость`: Условно `Тип`: String `Длина`: 255
bank_zip_code	Почтовый индекс банка.	`Необходимость`: Условно `Тип`: String `Длина`: 255
bank_province	Штат банка.	`Необходимость`: Условно `Тип`: String `Длина`: 255
bank_area	Область банка	`Необходимость`: Условно `Тип`: String `Длина`: 255
routing_number	Номер маршрута, используется для определения отдела банка в Китае.	`Необходимость`: Условно `Тип`: String `Длина`: 16
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 `Длина`: 256
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 `Длина`: 64k
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 `Длина`: 128
preferred_language	Предпочтительный язык.	`Необходимость`: Опционально `Тип`: String `Длина`: 2
customer_level	Уровень клиента в системе CMS.	`Необходимость`: Опционально `Тип`: Varchar `Длина`: 32
customer_id	Идентификатор клиента в системе CMS. Параметр становится обязательным, если включена система CMS в режиме определения клиента Платёжным шлюзом.	`Необходимость`: Опционально `Тип`: Int `Длина`: 10
merchant_customer_identifier	Идентификатор клиента-продавца в системе CMS. Параметр становится обязательным, если включена система CMS в режиме CRM.	`Необходимость`: Опционально `Тип`: Varchar `Длина`: 64
card_recurring_payment_id	Токенизированный идентификатор владельца карты. Нужно отправлять или параметр card_recurring_payment_id или комбинацию из credit_card_number, card_printed_name, expire_month и expire_year, но не все в одном запросе. Для создания card_recurring_payment_id см. /api/v4/create-card-ref. Примечание: ля сценария оплаты на карту внутри системы, эта карта рассматривается как источник, и к ней будут относиться все процессинговые ограничения, списки и проверки мошенничества.	`Необходимость`: Условно `Тип`: Long

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

Примечание

Ответ имеет заголовок 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/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

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

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

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

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

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

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

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

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

Коллекция Postman

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

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

Debug form

URL
parameters
login	login should be used as Consumer Public for OAuth

Normalized parameters string to sign, according to OAuth 1.0a rules

POST body parameters to submit

OAuth 1.0a headers to submit.

HEX Encoded Signature

^{* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.}

Base64 Encoded Signature

^{* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.}