Баланс счёта

Для работы с балансами счетов должно быть выдано разрешение ReadBalances.

Баланс показывает, сколько денег на счёте и сколько из них доступно прямо сейчас. Через API вы можете получать остатки по одному или всем счетам, видеть заблокированные суммы и отслеживать карточные операции ещё до того, как они попадут в выписку.

Методы Get Balance Info и Get Balances List возвращают остатки по счетам в реальном времени. Разница между ними простая: Get Balance Info — по одному счёту (нужен accountId), Get Balances List — сразу по всем вашим счетам.

Совет

accountId нужного счёта можно узнать методом Get Accounts List из раздела Счета

Банковский и доступный остаток

Важно различать два остатка:

• Банковский остаток — сколько денег числится на счёте
• Доступный остаток — сколько из них вы реально можете потратить прямо сейчас

Доступный остаток может быть меньше банковского — например, из-за блокировок на сумму или резерва по карточным операциям (о резерве — ниже).

Типы балансов

В ответе методов остаток приходит в разбивке по типам:

Тип	Что означает
OpeningAvailable	Начальный остаток на счёте без учёта овердрафта и блокировок
ClosingAvailable	Доступный остаток: за вычетом всех блокировок и без учёта овердрафта. Это деньги, свободные к использованию прямо сейчас
Expected	Сумма денег, заблокированных на счёте, в том числе в резерве по карточным операциям
OverdraftAvailable	Доступный лимит овердрафта. Приходит, только если на счёте подключён овердрафт

Инфо

Овердрафт — это кредитный лимит на счёте: он позволяет уйти в минус в пределах установленной суммы, когда собственных денег не хватает. OverdraftAvailable показывает, сколько из этого лимита ещё доступно. Это заёмные деньги банка, а не ваши, поэтому в ClosingAvailable они не входят.

Как посчитать нужную сумму

Клиенты обычно приходят с конкретным вопросом. Вот какой тип баланса смотреть:

Что нужно узнать	Какой тип смотреть
Сколько можно потратить прямо сейчас	ClosingAvailable
Сколько заблокировано (в резерве и других блокировках)	Expected
Сколько можно потратить с учётом овердрафта	ClosingAvailable + OverdraftAvailable
Начальный остаток без блокировок	OpeningAvailable

Формат данных

Остатки приходят в следующем виде:

• Данные приходят в массиве Data.Balance. В каждом элементе — свой accountId, тип баланса (type) и объект Amount с суммой и валютой.
• Сумма — в поле Amount.amount, валюта — в Amount.currency в формате ISO 4217 (например, RUB).
• Если у организации несколько счетов, в ответе Get Balances List баланс по каждому из них приходит отдельным элементом массива — ориентируйтесь на поле accountId, чтобы понять, к какому счёту относится остаток.
• Дата и время построения баланса — в поле dateTime (формат ISO 8601). Баланс отдаётся в реальном времени, то есть актуален на момент запроса.

Авторизованные карточные операции

Метод Get Authorized Card Transactions возвращает авторизованные карточные операции по конкретному счёту. Он удобен, чтобы отслеживать операции по карте, потому что в выписку они попадают не сразу.

Резерв — это деньги, которые блокируются на счёте сразу после оплаты картой или снятия наличных. Сумма становится недоступной и «ждёт» окончательного списания. Именно резерв показывает тип баланса Expected, и именно из-за него доступный остаток бывает меньше банковского.

Что важно помнить о таких операциях:

• Пока деньги в резерве, потратить их нельзя — учитывайте это при планировании расходов.
• Списание происходит, когда банк получает окончательное требование от платёжной системы. Обычно это 3–5 рабочих дней, иногда — до 30.
• В банковскую выписку операция попадает с датой списания, а не с датой покупки. Поэтому Get Authorized Card Transactions и нужен: он показывает то, что уже произошло по карте, но ещё не отразилось в выписке.

Как часто запрашивать баланс

Баланс отдаётся в реальном времени, но опрашивать его в цикле не нужно. Рекомендации:

• Запрашивайте баланс тогда, когда он действительно нужен: перед проведением платежа, при открытии экрана с остатком, по действию пользователя.
• Чтобы узнавать об изменениях, не опрашивая API, подпишитесь на вебхуки о входящих (incomingPayment) и исходящих (outgoingPayment) платежах — и запрашивайте баланс уже по факту события.
• Если нужен регулярный опрос, разумный интервал — не чаще одного раза в минуту на счёт. Более частые запросы не дадут более свежих данных, но создадут лишнюю нагрузку.