Платежи и выплаты/Статические кошельки

Статические кошельки

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

Открыть в 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-код адреса депозита в формате data URI (Base64). Для статических кошельков всегда присутствует, поскольку адрес назначается при создании.

Список кошельков

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

Запрос

Оба endpoint'а принимают один параметр:

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 — сумма, зачисленная на баланс мерчанта после удержания комиссии.

Webhook'и статических кошельков

Когда на статический кошелёк поступает платёж, система отправляет webhook на url_callback.

Формат webhook'а для статических кошельков отличается от обычных webhook'ов платежей. В частности, webhook'и статических кошельков содержат поле 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"
}

Webhook'и статических кошельков не содержат url и expires_at (поскольку адрес постоянный, а не сессионный). При этом они содержат exchange_rate и created_at.

Описание полей

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

Лучшие практики

Уникальный order_id — используйте уникальный order_id для каждого пользователя или заказа
Идемпотентность — проверяйте txid перед обработкой, чтобы избежать двойных зачислений
Проверяйте подпись — ВСЕГДА проверяйте подпись sign перед зачислением средств
Используйте merchant_amount — зачисляйте пользователям именно merchant_amount, а не payment_amount