# Баланс карты

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

## Endpoint

```
GET /cards/:id/balance
```

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

## Пример

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

## Ответ

```json
{
  "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` | Карта собрана, но ещё не привязана к мосту |