История баланса

Журнал всех движений баланса компании: пополнения, списания за ордера, заморозки, возвраты, операции по картам. Это источник правды для сверки — именно здесь видно, когда деньги действительно двигались.

Endpoint

GET /wallets/balance-history?limit=50&before=2026-08-14T00:00:00Z

Параметры

Параметр	Тип	Описание
`operationType`	string	Точное совпадение по типу операции
`from`	ISO datetime	Только записи с `createdAt >= from`
`to`	ISO datetime	Только записи с `createdAt <= to`
`limit`	integer	1–200, по умолчанию 50
`before`	ISO datetime	Курсор: записи с `createdAt < before`

Даты без времени считаются началом суток по UTC: to=2026-08-14 не включит записи 14 августа — передавайте время явно. Некорректная дата — 400 BAD_REQUEST.

Пример

curl 'https://b2b.lumowallet.io/wallets/balance-history?from=2026-08-01&limit=100' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "entries": [
    {
      "id": "7f2b12a4-5c3d-4e6f-8a9b-0c1d2e3f4a5b",
      "createdAt": "2026-08-14T10:00:00.000Z",
      "operationType": "order_success_settlement",
      "referenceId": "660e8400-e29b-41d4-a716-446655440001",
      "balanceBefore": 1052.63,
      "balanceAfter": 1000,
      "deltaBalance": -52.63,
      "frozenBefore": 52.63,
      "frozenAfter": 0,
      "deltaFrozen": -52.63,
      "metadata": { "amountUsdt": 52.63 }
    }
  ]
}

Как читать запись

balanceBefore / balanceAfter / deltaBalance — баланс компании до и после операции и его изменение.
frozenBefore / frozenAfter / deltaFrozen — то же для замороженной суммы. Заморозка не списание: средства ещё ваши, но недоступны, пока ордер или заявка в работе. Доступно к тратам balance − frozen.
operationType — что произошло, см. таблицы ниже.
referenceId — к чему относится запись. Что именно в нём лежит, зависит от типа операции — см. колонку referenceId в таблицах.
metadata — подробности операции: суммы, связанные id. Состав зависит от типа и может пополняться.

Запись появляется, только когда баланс или заморозка действительно изменились.

Типы операций

Депозиты

`operationType`	Описание	`referenceId`
`company_deposit_credit`	Депозит на адрес компании зачислен на баланс	id компании
`company_deposit_fee_charge`	Комиссия за обработку депозита на кошелёк пользователя	id депозита пользователя

Ордера

`operationType`	Описание	`referenceId`
`order_frozen_increase`	Сумма ордера заморожена при accept	id ордера
`order_success_settlement`	Ордер прошёл, сумма списана	id ордера
`order_failed_unfreeze`	Ордер не прошёл, заморозка снята (списания не было)	id ордера
`order_failed_refund_after_success`	Уже списанная сумма возвращена	id ордера
`order_success_settlement_after_failed`	Оплата пришла после истечения срока: ордер из `failed` перешёл в `success`, сумма списана (заморозка была снята раньше)	id ордера
`order_success_settlement_after_dispute`	Диспут закрыт в пользу платежа, списание подтверждено	id ордера
`order_partial_refund`	Частичный возврат по исполненному ордеру от платёжной стороны — без смены статуса ордера	id ордера
`dispute_resolve_refund`	Диспут решён возвратом: сумма вернулась или снята заморозка	id ордера
`dispute_resolve_partial_refund`	Диспут решён частичным возвратом	id ордера
`dispute_resolve_confirm`	Диспут отклонён, списание подтверждено	id ордера

Карты

`operationType`	Описание	`referenceId`
`card_request_freeze`	Резерв под выпуск карты	ваш `Idempotency-Key` из `POST /cards/request`
`card_opening_fee_debit`	Карта выдана: комиссия за выпуск списана, резерв снят	id карты
`card_request_release`	Резерв снят без выпуска: запрос на выпуск не прошёл, или повтор вернул уже выданную карту	id карты или пусто
`card_request_cancel_release`	Заявка отменена, резерв снят	id заявки
`card_recharge_debit`	Списание за пополнение карты	id карты
`card_recharge_refund_bridge_error`	Эквайер сразу отклонил пополнение, списание возвращено	id карты
`card_recharge_failed_refund`	Пополнение не прошло, средства возвращены	id пополнения
`card_recharge_refund`	Возврат после успешного пополнения	id пополнения
`card_closure_refund`	Остаток закрытой карты за вычетом комиссии возвращён на баланс	id карты

Выплаты

`operationType`	Описание	`referenceId`
`payout_charge`	Списание при создании выплаты	id выплаты
`payout_refund`	Выплата не состоялась, средства возвращены	id выплаты
`payout_refund_reversal`	Выплату после возврата всё же исполнили — сумма списана повторно	id выплаты

Служебные

`operationType`	Описание	`referenceId`
`admin_balance_topup`	Ручное пополнение баланса администратором Lumo	id компании
`company_balance_update`	Ручная корректировка без указанного типа	пусто

:::note Не завязывайтесь на закрытый список

Список типов пополняется, поэтому не считайте неизвестный operationType ошибкой — показывайте его как есть, а логику стройте на deltaBalance / deltaFrozen.

:::

Выгрузка в CSV

GET /wallets/balance-history.csv?from=2026-08-01T00:00:00Z&to=2026-08-14T23:59:59Z

Отдаёт файл со всеми записями за период (а не одной страницей), с теми же фильтрами operationType / from / to — до 50 000 последних записей. UTF-8 с BOM — Excel открывает кириллицу корректно, имя файла приходит в Content-Disposition.

curl -OJ 'https://b2b.lumowallet.io/wallets/balance-history.csv?from=2026-08-01' \
  -H 'X-API-Key: YOUR_API_KEY'

Колонки: createdAt, operationType, deltaBalance, balanceAfter, deltaFrozen, frozenAfter, referenceId, metadata.

Пагинация

Курсорная: берёте createdAt последней записи и передаёте в before следующего запроса. Ответ короче limit — значит конец. Для выгрузки за период используйте CSV: он не постраничный.

Права

Нужно право balance.read.