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

Payout API

Надсилайте виплати з мерчант-балансу на будь-яку блокчейн-адресу.

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

Для всіх endpoints 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 для webhooks виплат. Не вказуйте, щоб вимкнути webhooks для цієї виплати
memostring | nullніDestination tag / memo. Зараз використовується лише мережами TON та SOL; макс. 255 символів
from_currencystringніВихідний баланс, з якого списати кошти та автоматично конвертувати у currency у момент виплати. Дозволяє виплачувати у волатильних активах (BTC, ETH, …), тримаючи баланс у стейблкоїні як USDT — вам не потрібно самим тримати волатильну криптовалюту. Передайте "USDT", щоб списати з USDT-балансу
fee_optionstringніЯк стягуються комісії. deduct (за замовчуванням) — мережева та платформна комісії віднімаються від amount, отримувач отримує amount - fees. add — комісії додаються зверху, з мерчанта списується amount + fees, отримувач отримує рівно 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 - fees). Передайте fee_option: add, щоб стягувати комісії зверху — отримувач отримує рівно amount, а з мерчанта списується amount + fees.

Розрахувати виплату

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

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"
  }
}

Лише попередній перегляд. Цей ендпоінт лише для читання — баланс не списується і запис виплати не створюється. Викликайте стільки разів, скільки потрібно, щоб показати розкладку комісій у вашому UI.

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

Отримати статус запиту на виплату.

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 (див. Error types нижче). 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 не було надано, для цієї виплати webhooks не надсилаються.

  • Метод: 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"
}

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