Баланс карты

Баланс по карте от эквайера — по одной карте, по выбранным картам или по всем сразу. Нужно право cards.read.

GET /cards/:id/balance

Доступно только для карт в статусе assigned, для остальных — 400 CARD_NOT_ACTIVE.

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:56.000Z"
}

Баланс отдаётся из последнего полученного от эквайера значения. Если оно старше ~60 секунд, обновление запрашивается в фоне, а в ответ приходит последнее известное значение — оно может быть старше нескольких минут. Насколько оно свежее, показывает fetchedAt.

GET /cards/balances?limit=100&after={cardId}

Последние известные балансы всех карт компании одним запросом — удобно для списков и сверки, без запроса на каждую карту.

curl 'https://b2b.lumowallet.io/cards/balances?limit=100' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "data": [
    {
      "cardId": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
      "externalId": "user-42-card-1",
      "balance": "42.17",
      "currency": "USD",
      "fetchedAt": "2026-10-02T09:58:11.000Z"
    },
    {
      "cardId": "8c7f1823-0d43-4618-86ee-fa0c77643cb2",
      "externalId": null,
      "balance": null,
      "currency": null,
      "fetchedAt": null
    }
  ],
  "meta": {
    "limit": 100,
    "nextCursor": "8c7f1823-0d43-4618-86ee-fa0c77643cb2"
  }
}

• В выдаче все карты компании, включая закрытые, отсортированные по cardId.
• Это последние известные значения: их обновляет фоновая синхронизация, к эквайеру за каждой картой запрос не идёт. Свежесть — в fetchedAt.
• balance — строка без округления. Если баланс неизвестен — у карты не в статусе assigned или эквайер его ещё не отдал, — balance, currency и fetchedAt равны null. null — это «неизвестно», а не ноль.
• fetchedAt — когда баланс получен от эквайера, а не время ответа API.
• Следующая страница: передайте meta.nextCursor в after. На последней странице nextCursor равен null.

Некорректные limit или after дают 400 VALIDATION_ERROR. Если эквайер не ответил, запрос целиком завершается ошибкой 502 — повторите позже.

POST /cards/balances/query

Балансы конкретных карт по списку ID — без обхода всех карт страницами. Карты можно указать нашими cardId, своими externalId или и теми, и другими в одном запросе.

Нужен хотя бы один ID, всего — не больше 100 по обоим массивам вместе.

curl -X POST 'https://b2b.lumowallet.io/cards/balances/query' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "cardIds": ["1b4e28ba-2fa1-41d2-883f-0016d3cca427"],
    "externalIds": ["user-42-card-2", "user-77-card-1"]
  }'

{
  "data": [
    {
      "cardId": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
      "externalId": "user-42-card-1",
      "balance": "42.17",
      "currency": "USD",
      "fetchedAt": "2026-10-02T09:58:11.000Z"
    },
    {
      "cardId": "8c7f1823-0d43-4618-86ee-fa0c77643cb2",
      "externalId": "user-42-card-2",
      "balance": "0.00",
      "currency": "USD",
      "fetchedAt": "2026-10-02T09:58:11.000Z"
    }
  ],
  "notFound": {
    "cardIds": [],
    "externalIds": ["user-77-card-1"]
  }
}

• Элементы data — в том же формате, что в GET /cards/balances, и с теми же правилами: последние известные значения, свежесть в fetchedAt, null — «неизвестно», а не ноль.
• Порядок — как в запросе: сначала карты из cardIds, затем из externalIds. Карта, указанная и по cardId, и по externalId, в ответе один раз.
• ID, которых нет среди карт вашей компании, — в notFound. Карты других компаний не возвращаются никогда.

Пустой запрос, больше 100 ID, cardId не в формате UUID или пустой externalId дают 400 VALIDATION_ERROR. Если эквайер не ответил, запрос целиком завершается ошибкой 502 — повторите позже.

Если у компании включен cardsTestMode, все три эндпоинта возвращают синтетический баланс 123.45 USD (для GET /cards/balances и POST /cards/balances/query — у карт в статусе assigned).