Sign in
Платежи и выплаты/Payout API

Payout API

Отправка выплат с баланса мерчанта на любой блокчейн-адрес.

Payout API позволяет программно выводить средства с баланса мерчанта на любой блокчейн-адрес.

Для всех endpoint'ов Payout вы должны использовать отдельный Payout API key для расчёта подписи sign. Этот ключ отличается от обычного API key и создаётся в настройках проекта.

Создать выплату

Создаёт запрос на выплату с баланса мерчанта.

POST/v1/payout

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

ПолеТипОбязательноеОписание
currencystringдаВалюта вывода (см. References)
networkstringдаКод сети (см. References)
amountstringдаСумма вывода
to_addressstringдаБлокчейн-адрес получателя
order_idstringнетКлюч идемпотентности — уникальный в рамках проекта. Повторный POST с тем же order_id не создаёт новую выплату — возвращается уже существующая
url_callbackstringнетURL для webhook'ов выплаты. Не указывайте, чтобы отключить webhook'и для этой выплаты
memostring | nullнетDestination tag / memo. Сейчас используется только для сетей TON и SOL; не более 255 символов
from_currencystringнетИсходный баланс, с которого списать средства и авто-конвертировать в currency в момент выплаты. Позволяет выплачивать в волатильных активах (BTC, ETH, …), держа баланс в стейблкоине USDT — не нужно самим хранить волатильную крипту. Передайте "USDT", чтобы списать с USDT-баланса
fee_optionstringнетКто платит комиссии. deduct (по умолчанию) — комиссия сети + платформы вычитается из amount, получатель получает amount - комиссии. add — комиссии добавляются сверху, с мерчанта списывается amount + комиссии, получателю приходит ровно amount

Идемпотентность. В рамках проекта выплата уникальна по order_id. Повторная отправка POST с тем же order_id безопасна — API вернёт уже существующую выплату вместо создания дубликата. Всегда передавайте order_id для продакшен-выплат.

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

Shell
curl -X POST https://api.2328.io/api/v1/payout \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"TRX","network":"TRX-TRC20","amount":"1.00","to_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","order_id":"9ed25264-8be4-439f-acf5-2a8732538d27","url_callback":"https://your-site.com/webhook/payout","memo":null,"fee_option":"deduct"}'

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

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dea62-1727-72aa-ac2c-eaf2ade193ef",
    "order_id": "9ed25264-8be4-439f-acf5-2a8732538d27",
    "status": "pending",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "1.00",
    "merchant_amount": "1",
    "network_amount": "0.89",
    "amount_usd": "0.33",
    "to_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "memo": null,
    "txid": null,
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-02T23:29:50+03:00",
    "updated_at": "2026-05-02T23:29:50+03:00"
  }
}

Комиссии. По умолчанию fee_option: deduct — комиссия сети + платформы вычитается из amount (получатель получает amount - комиссии). Передайте fee_option: add, чтобы взимать комиссии сверху — получатель получит ровно amount, а с мерчанта спишется amount + комиссии.

Рассчитать выплату

Оценивает суммы и комиссии вывода без создания выплаты и без списания с баланса. Используйте, чтобы показать пользователю точную сумму, которую он получит (или заплатит), до подтверждения.

POST/v1/payout/calc

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

Идентичны Создать выплату — те же поля, та же подпись. Поля order_id, url_callback, to_address и memo принимаются, но игнорируются: выплата не сохраняется, callback'и не отправляются.

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

Shell
curl -X POST https://api.2328.io/api/v1/payout/calc \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE" \
  -d '{"currency":"USDT","network":"TRX-TRC20","amount":"100","fee_option":"add"}'

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

JSON
{
  "state": 0,
  "result": {
    "currency": "USDT",
    "network": "TRX-TRC20",
    "amount": "100",
    "fee_option": "add",
    "merchant_amount": "103.00000000",
    "network_amount": "100",
    "total_fee": "3.00000000",
    "total_fee_usd": "3.00000000"
  }
}

Только превью. Эндпоинт только для чтения — баланс не списывается, запись выплаты не создаётся. Вызывайте сколько нужно, чтобы отобразить раскладку комиссий в интерфейсе.

Статус выплаты

Получение статуса запроса на выплату.

GET/v1/payout/status/{uuid}

Параметры пути

ПолеТипОбязательноеОписание
uuidstringдаUUID выплаты (из result.uuid при создании)

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

JSON
{
  "state": 0,
  "result": {
    "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
    "order_id": "4dfdcc84402b1185b71cbe399321533e",
    "status": "completed",
    "currency": "TRX",
    "network": "TRX-TRC20",
    "amount": "3.00",
    "merchant_amount": "3.00",
    "network_amount": "3.00",
    "amount_usd": "1.04",
    "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
    "memo": null,
    "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
    "block_number": null,
    "error_type": null,
    "created_at": "2026-05-07T00:08:38+03:00",
    "updated_at": "2026-05-07T00:08:54+03:00",
    "from_currency": "USDT",
    "debited_amount": "1.050735",
    "debited_currency": "USDT"
  }
}

Для этого GET-запроса подпись считается от пустого тела: hash_hmac('sha256', base64_encode(''), $apiKey)

Поля ответа

Поля, возвращаемые в result для POST /v1/payout и GET /v1/payout/status/{uuid}:

ПолеТипОписание
uuidstringUUID выплаты, назначенный системой
order_idstringВаш внутренний идентификатор выплаты (уникальный в рамках проекта)
statusstringТекущий статус выплаты (см. ниже)
currencystringВалюта вывода
networkstringКод сети
amountstringСумма вывода в исходном виде
merchant_amountstringСумма, списанная с баланса мерчанта
network_amountstringСумма, фактически отправленная в сеть (после комиссий сети + платформы)
amount_usdstringЭквивалент суммы вывода в USD
to_addressstringБлокчейн-адрес получателя
memostring | nullDestination tag / memo (TON, SOL). Иначе null
txidstring | nullХеш транзакции в блокчейне. null, пока транзакция не отправлена
block_numberint | nullНомер блока, в который включена транзакция. null, пока не включена
error_typestring | nullПричина при status = failed (см. «Типы ошибок» ниже). Иначе null
created_atstring (ISO 8601)Время создания выплаты
updated_atstring (ISO 8601)Время последнего изменения статуса
from_currencystring | nullИсходный баланс, с которого было списание при авто-конвертации (например, USDT для выплаты в BTC). null, если конвертация не использовалась
debited_amountstring | nullСумма, фактически списанная с исходного баланса после конвертации. Присутствует, только если используется авто-конвертация
debited_currencystring | nullВалюта debited_amount — баланс, с которого были списаны средства

Статусы выплат

Поле status принимает следующие значения:

СтатусОписание
pendingСоздана, ожидает обработки
completedУспешно завершена — заполнен txid
failedОшибка отправки — см. error_type
cancelledОтменена

Типы ошибок

Когда status = failed, поле error_type указывает на причину:

КодОписание
aml_riskВыплата заблокирована AML-проверкой (адрес получателя помечен как высокорисковый)

Webhook-уведомления

При смене статуса выплаты система отправляет POST webhook на URL url_callback, переданный при создании выплаты. Если url_callback не был указан, webhook'и для этой выплаты не отправляются.

  • Метод: POST
  • Content-Type: application/json
  • Подпись: поле sign в теле запроса, рассчитанное с использованием Payout API key (тот же ключ, которым подписываются запросы на выплату).

Payload повторяет объект result из GET /v1/payout/status/{uuid} плюс поле sign для проверки.

Payload

JSON
{
  "uuid": "019dff1f-0dbd-7277-8d45-271e7775388f",
  "order_id": "4dfdcc84402b1185b71cbe399321533e",
  "status": "completed",
  "currency": "TRX",
  "network": "TRX-TRC20",
  "amount": "3.00",
  "merchant_amount": "3.00",
  "network_amount": "3.00",
  "amount_usd": "1.04",
  "to_address": "THauRv5tcucQRohXg8NiyGTk16DX1XQG5x",
  "memo": null,
  "txid": "9242e533703704ef3eaba840f70b4a26333e72c943377ee375fea17badb53def",
  "block_number": null,
  "error_type": null,
  "created_at": "2026-05-07T00:08:38+03:00",
  "updated_at": "2026-05-07T00:08:54+03:00",
  "from_currency": "USDT",
  "debited_amount": "1.050735",
  "debited_currency": "USDT",
  "sign": "925ad7bf3d6841864101f7cc2c7e30652e70a06cdb04dbe07a0129480000ce4a"
}

Проверка подписи. Используйте тот же алгоритм, что и для webhook'ов платежей, но подписывайте Payout API key вместо обычного API key. Удалите поле sign, сериализуйте оставшийся payload в JSON, закодируйте в Base64, затем рассчитайте hash_hmac('sha256', $base64, $payoutApiKey) и сравните с полученным sign.