Баланс карты

Live-баланс по карте напрямую от эквайера.

Endpoint

GET /cards/:id/balance

Доступно только для карт в статусе assigned. Для requested, failed, retired — endpoint вернёт 400.

Пример

curl 'https://b2b.lumowallet.io/cards/8c7f1823-0d43-4618-86ee-fa0c77643cb2/balance' \
  -H 'X-API-Key: YOUR_API_KEY'

Ответ

{
  "balance": "42.17",
  "currency": "USD",
  "fetchedAt": "2026-05-01T12:34:56Z"
}

Поля

Поле	Тип	Описание
`balance`	string	Баланс в виде десятичной строки от эквайера
`currency`	string	ISO 4217 (обычно `USD`)
`fetchedAt`	datetime	Когда мост получил (или закэшировал) это значение

Кэширование

Бэкенд проксирует запрос напрямую в upay-bridge. На стороне моста значение кэшируется на ~60 секунд, чтобы не нагружать эквайер. Если за этот период вы вызовете /balance несколько раз — получите один и тот же fetchedAt.

Тестовый режим

Если у компании включен cardsTestMode, endpoint возвращает синтетический ответ {"balance":"123.45","currency":"USD"} без обращения к мосту.

Ошибки

Код	Ошибка	Описание
400	`CARD_NOT_ACTIVE: card status is <status>`	Карта не в статусе `assigned`
401	`Unauthorized`	Неверный API-ключ
404	Card not found	Карта не принадлежит компании или её нет
422	`Card is not yet active`	Карта собрана, но ещё не привязана к мосту