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

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

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`

Пример

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

{
  "entries": [
    {
      "id": "7f2b12a4-...",
      "createdAt": "2026-08-14T10:00:00Z",
      "operationType": "order_success_settlement",
      "referenceId": "660e8400-e29b-41d4-a716-446655440001",
      "balanceBefore": 1052.63,
      "balanceAfter": 1000.00,
      "deltaBalance": -52.63,
      "frozenBefore": 52.63,
      "frozenAfter": 0,
      "deltaFrozen": -52.63,
      "metadata": { "walletOrderId": "..." }
    }
  ]
}

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

deltaBalance — изменение доступного баланса. Ноль означает, что деньги не двигались (например, только сняли заморозку).
deltaFrozen — изменение замороженной суммы. Заморозка не списание: средства ещё ваши, но недоступны, пока ордер в работе.
referenceId — к чему относится запись: orderId, depositId, rechargeId или cardId, в зависимости от типа операции. По нему сводятся движения с ордерами и диспутами.
balanceAfter — баланс сразу после операции, удобно для сверки.

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

Основные, которые встретятся в обычной работе:

Депозиты

`operationType`	Описание
`company_deposit_credit`	Депозит зачислен на баланс
`company_deposit_fee_charge`	Удержана комиссия за приём депозита

Ордера

`operationType`	Описание
`order_frozen_increase`	Сумма ордера заморожена при создании
`order_success_settlement`	Ордер прошёл, сумма списана
`order_failed_unfreeze`	Ордер не прошёл, заморозка снята (списания не было)
`order_failed_refund_after_success`	Уже списанная сумма возвращена
`order_success_settlement_after_dispute`	Диспут отклонён, списание подтверждено
`order_partial_refund`	Возвращена часть суммы ордера

Карты

`operationType`	Описание
`card_request_freeze`	Резерв под выпуск карты
`card_request_release`	Резерв освобождён (заявка отменена)
`card_opening_fee_debit`	Комиссия за выпуск карты
`card_recharge_debit`	Списание за пополнение карты
`card_recharge_refund`	Возврат пополнения
`card_recharge_failed_refund`	Пополнение не прошло, средства возвращены
`card_closure_refund`	Остаток закрытой карты возвращён на баланс

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

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

:::

Выгрузка в CSV

GET /wallets/balance-history.csv?from=2026-08-01&to=2026-08-14

Отдаёт файл со всеми записями за период (а не одной страницей), с теми же фильтрами operationType / from / to. 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.