История транзакций

Операции по картам (покупки, возвраты и другие списания и зачисления) синхронизируются от эквайера. История доступна через REST, новые операции приходят вебхуком. Нужно право cards.read.

Пополнения карт в эту историю не входят — они в истории пополнений.

GET /cards/:id/transactions?limit=50&before=2026-04-23T00:00:00Z

Фильтра по периоду у этой ручки нет — для периода используйте общую ленту с cardId на своей стороне или CSV-выгрузку по карте.

GET /cards/transactions?from=2026-08-01T00:00:00Z&to=2026-08-14T23:59:59Z

Та же лента, но по всем картам компании — не нужно ходить по каждой отдельно. В каждой строке есть cardId и cardMaskedPan, чтобы понять, чья это операция.

Даты без времени считаются началом суток по UTC: to=2026-08-14 не включит операции 14 августа — передавайте время явно. Некорректная дата — 400 BAD_REQUEST.

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

[
  {
    "id": "7f2b12a4-...",
    "cardId": "8c7f1823-...",
    "cardMaskedPan": null,
    "processorBillId": "88120394",
    "processorOrderNo": "ORD55102",
    "processorParentId": "77001122",
    "type": 2,
    "typeName": "Consumption",
    "status": 4,
    "statusName": "Posted",
    "direction": 2,
    "directionName": "Pay",
    "amount": "49.99",
    "fee": "0.50",
    "currency": "USD",
    "originalAmount": "4599",
    "originalCurrency": "RUB",
    "merchantName": "GOOGLE PLAY",
    "merchantMcc": "5816",
    "ditchCode": "straitsx",
    "reason": null,
    "transactionTime": "2026-04-23T12:05:22.000Z",
    "syncedAt": "2026-04-23T12:06:00.000Z"
  }
]

Сортировка — по transactionTime DESC.

typeName, statusName и directionName приходят от эквайера как есть. Значения, которые встречаются:

Список может пополняться — неизвестные значения показывайте как есть. Строки пополнений (typeName: Recharge/Collateral) из REST-выдачи исключены, но приходят в вебхуках, см. ниже.

Покупка приходит от эквайера двумя строками: сначала авторизация (statusName: Unposted), затем — в среднем через 29 часов — её проведение (Posted) или отмена (Cancelled) отдельной строкой с новым ID операции.

В REST-выдаче мы схлопываем такую пару сами: пока по авторизации нет финальной строки, вы видите авторизацию; когда финальная строка пришла, авторизация из выдачи пропадает и остаётся только финальная строка.

Связать финальную строку с авторизацией, которую вы сохранили раньше (например, из вебхука card.transaction.created), можно по processorParentId: у авторизации и её финальной строки он общий. В вебхуках это поле называется upayParentId.

Обычно проведение приходит в течение двух суток. Авторизацию, которая висит без проведения дольше 7 дней, можно считать несостоявшейся.

Карты выпускаются в USD, поэтому покупка в другой валюте приходит уже сконвертированной. Исходная сумма при этом сохраняется:

{
  "amount": "19.6248",
  "currency": "USD",
  "originalAmount": "910",
  "originalCurrency": "TRY",
  "merchantName": "CHURROS TIME CAFE TURIZM"
}

То есть чек был на 910 ₺, а с карты списали 19.62 $. Поля заполнены у всех покупок и возвратов, в том числе у покупок в долларах. У служебных строк — пополнений и деактивации карты — оба поля null.

GET /cards/transactions.csv?from=2026-08-01T00:00:00Z&to=2026-08-14T23:59:59Z
GET /cards/:id/transactions.csv?from=2026-08-01T00:00:00Z&to=2026-08-14T23:59:59Z

Отдаёт файл: операции и пополнения одной лентой, колонка type их различает. UTF-8 с BOM — Excel открывает кириллицу корректно. Имя файла (с периодом внутри) приходит в Content-Disposition.

:::warning Большие периоды выгружайте частями

Сейчас операции в выгрузке могут обрываться примерно на тысяче последних строк за период. Если операций больше, выгружайте период частями и сверяйтесь с лентой GET /cards/transactions. Пополнений в файл попадает до 50 000.

:::

curl -OJ 'https://b2b.lumowallet.io/cards/transactions.csv?from=2026-08-01' \
  -H 'X-API-Key: YOUR_API_KEY'

Колонки: transactionTime, type, cardMaskedPan, amount, currency, originalAmount, originalCurrency, fee, feeCurrency, debitUsdt, merchantName, mcc, status, reason, reference.

• type — typeName операции в нижнем регистре (consumption, refund, …) или recharge для пополнения.
• amount со знаком: минус — деньги ушли с карты. У пополнения amount — сумма пополнения (USD), а debitUsdt — сколько за него списывалось с баланса компании (сумма + комиссия). У пополнений failed и refunded эта сумма уже возвращена — смотрите колонку status.
• status — statusName операции или статус пополнения.
• reference — processorBillId операции или ID пополнения.
• В колонке mcc — тот же merchantMcc, что и в JSON; у операций без MCC она пустая.

Новые операции приходят событием card.transaction.created — как только мы получили строку от эквайера. Проведение ранее пришедшей авторизации приходит отдельным событием card.transaction.settled.

{
  "event": "card.transaction.created",
  "id": "7f2b12a4-...",
  "cardId": "8c7f1823-...",
  "cardMaskedPan": "4466********1234",
  "upayBillId": "88120394",
  "upayParentId": "77001122",
  "type": 2,
  "typeName": "Consumption",
  "status": 5,
  "statusName": "Unposted",
  "direction": 2,
  "amount": "19.6248",
  "fee": "0",
  "currency": "USD",
  "originalAmount": "910",
  "originalCurrency": "TRY",
  "merchantName": "CHURROS TIME CAFE TURIZM",
  "merchantMcc": "5814",
  "transactionTime": "2026-08-14T10:00:00.000Z",
  "createdAt": "2026-08-14T10:00:20.000Z"
}

:::warning Авторизация и проведение — это одна операция

В вебхуках пары не схлопываются: на авторизацию приходит created, на её проведение — settled с новым upayBillId и тем же upayParentId. Связывайте их по upayParentId, иначе один платёж посчитается дважды. В REST-выдаче это же значение называется processorParentId.

:::

Состав события отличается от REST-выдачи — см. Webhooks по картам.

Cursor-стиль: запросили страницу, взяли transactionTime последней записи, передали в before следующего запроса.

Строки пополнений отбрасываются уже после выборки страницы, поэтому страница может оказаться короче limit, хотя более старые операции есть. Не считайте короткую страницу концом — продолжайте, пока ответ не станет пустым.

При cardsTestMode = true операций нет: обе ленты возвращают пустой список, CSV содержит только пополнения.