Платежі та виплати/Статичні гаманці

Статичні гаманці

Постійні депозитні адреси, прив'язані до конкретного замовлення або користувача, ідеальні для повторюваних та довгострокових платежів.

Відкрити як Markdown·llms.txt

Статичні гаманці — це постійні адреси для прийому криптовалютних платежів. Вони пов'язані з конкретним order_id і є унікальними за комбінацією project_id + order_id + currency + network.

Використовуйте статичні гаманці для:

Повторюваних депозитів від одного й того самого користувача
Довгострокових платіжних адрес, що відображаються у профілі користувача
Високооб'ємних потоків депозитів, де ви хочете мати стабільну адресу для кожного користувача

Створити статичний гаманець

POST/v1/static-wallet

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

Поле	Тип	Обов'язкове	Опис
`currency`	string	так	Криптовалюта (USDT, BTC, ETH тощо)
`network`	string	так	Код мережі
`order_id`	string	так	Ваш ID замовлення/користувача (до 255 символів)
`label`	string	ні	Мітка гаманця (до 255 символів)
`url_callback`	string	так	URL для webhook-сповіщень
`invite_code`	string	ні	Код реферера

Приклад запиту

JSON

{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}

Приклад відповіді

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

Інформація про гаманець

Отримайте інформацію про статичний гаманець за uuid або address.

POST/v1/static-wallet/info

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

Поле	Тип	Обов'язкове	Опис
`uuid`	string	так*	UUID статичного гаманця
`address`	string	так*	Блокчейн-адреса гаманця

Принаймні одне з полів uuid або address є обов'язковим.

Приклад відповіді

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

total_received — сума всіх депозитів, отриманих цим гаманцем, у currency.
transactions_count — кількість отриманих депозитів на цей момент.
qr — QR-код депозитної адреси, закодований у base64 (data URI) (завжди присутній для статичних гаманців, адресу призначають під час створення).

Список гаманців

POST/v1/static-wallet/list

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

Поле	Тип	Обов'язкове	Опис
`status`	string	ні	Фільтрувати за статусом (`active`, `inactive`)
`currency`	string	ні	Фільтрувати за валютою
`network`	string	ні	Фільтрувати за мережею
`order_id`	string	ні	Фільтрувати за order_id
`page`	int	ні	Номер сторінки (за замовчуванням: 1)
`per_page`	int	ні	Елементів на сторінці (за замовчуванням: 20, максимум: 100)

Приклад відповіді

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

Увімкнути / вимкнути гаманець

Перемикає, чи приймає статичний гаманець нові платежі.

POST/v1/static-wallet/disable

POST/v1/static-wallet/enable

Запит

Обидва endpoints приймають єдиний параметр:

JSON

{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}

Приклад відповіді

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}

Для enable status дорівнює "active", а message — "Static wallet enabled successfully".

Транзакції гаманця

Отримайте список усіх депозитів, отриманих статичним гаманцем.

POST/v1/static-wallet/transactions

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

Поле	Тип	Обов'язкове	Опис
`uuid`	string	так	UUID статичного гаманця
`date_from`	date	ні	Початкова дата (YYYY-MM-DD)
`date_to`	date	ні	Кінцева дата (YYYY-MM-DD)
`page`	int	ні	Номер сторінки (за замовчуванням: 1)
`per_page`	int	ні	Елементів на сторінці (за замовчуванням: 15, максимум: 5000)

Приклад відповіді

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}

fee_amount — платформна комісія, утримана з цього депозиту, у currency.
net_amount — сума, зарахована на мерчант-баланс після комісії.

Webhooks статичних гаманців

Коли на статичний гаманець надходить платіж, система надсилає webhook на url_callback.

Формат webhook для статичних гаманців відрізняється від звичайних webhooks платежів. Зокрема, webhooks статичних гаманців містять поле merchant_amount, яке слід використовувати для зарахування.

Payload webhook

JSON

{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

Webhooks статичних гаманців не містять url та expires_at (оскільки адреса є постійною, а не сесією). Вони містять exchange_rate та created_at.

Опис полів

Поле	Тип	Опис
`uuid`	string	UUID транзакції (рахунка) для цього депозиту
`order_id`	string	Ваш `order_id` статичного гаманця
`amount`	decimal (8 dp)	Отримана сума криптовалюти
`currency`	string	Отримана криптовалюта (відповідає `currency` гаманця)
`amount_usd`	decimal (8 dp)	Вартість у USD на момент отримання
`exchange_rate`	decimal	Використаний курс crypto / USD
`payer_currency`	string	Те саме, що й `currency`, для статичних гаманців
`payer_amount`	decimal (8 dp)	Те саме, що й `amount`, для статичних гаманців
`network`	string	Блокчейн-мережа
`address`	string	Адреса статичного гаманця
`payment_status`	string	Завжди `paid` для статичних
`txid`	string	Хеш блокчейн-транзакції
`payment_amount`	decimal (8 dp)	Те саме, що й `amount`
`merchant_amount`	decimal (18 dp)	Сума після утримання комісії — використовуйте її для зарахування
`created_at`	string (ISO 8601)	Коли депозит було отримано
`sign`	string (hex)	Підпис HMAC-SHA256 payload

Найкращі практики

Унікальний order_id — використовуйте унікальний order_id для кожного користувача або замовлення
Ідемпотентність — перевіряйте txid перед обробкою, щоб уникнути дублювання зарахувань
Перевіряйте підписи — ЗАВЖДИ перевіряйте підпис sign перед зарахуванням коштів
Використовуйте merchant_amount — зараховуйте користувачам на основі merchant_amount, а не payment_amount