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

Все операции по карте (покупки, возвраты, пополнения) синхронизируются от эквайера. История доступна через REST.

Endpoint

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

Параметры

Параметр	Тип	Описание
`limit`	integer	1–200, по умолчанию 50
`before`	ISO datetime	Cursor: вернёт транзакции с `transactionTime < before`
`from`	ISO datetime	Только операции с `transactionTime >= from`
`to`	ISO datetime	Только операции с `transactionTime <= to`

По всем картам сразу

GET /cards/transactions?from=2026-08-01&to=2026-08-14

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

Пополнения сюда не входят — они в GET /cards/recharges.

Пример

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

Ответ

[
  {
    "id": "7f2b12a4-...",
    "cardId": "8c7f1823-...",
    "processorBillId": "BILL0010023",
    "processorOrderNo": "ORD55102",
    "type": 1,
    "typeName": "purchase",
    "status": 2,
    "statusName": "succeeded",
    "direction": 1,
    "directionName": "debit",
    "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:22Z",
    "syncedAt": "2026-04-23T12:06:00Z"
  }
]

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

Поля

Поле	Описание
`processorBillId`	ID транзакции у эквайера — используйте для support-тикетов
`typeName`	`purchase` / `refund` / `reversal` / `recharge`
`statusName`	`pending` / `succeeded` / `failed`
`directionName`	`debit` (списание) / `credit` (приход на карту)
`amount`	Сумма операции в валюте карты (десятичная строка)
`originalAmount`	Сумма у мерчанта до конвертации в валюту карты. `null`, если конвертации не было
`originalCurrency`	Валюта мерчанта, например `TRY`. `null` вместе с `originalAmount`
`fee`	Комиссия эквайера (может быть `null`)
`merchantName`	Название торговой точки, как его прислал acquirer
`merchantMcc`	MCC — код категории торговой точки (`5816`, `5734`, …). Приходит у покупок, где его прислал эквайер; у пополнений, закрытий карты и строк без мерчанта — `null`
`ditchCode`	Канал эквайринга, а не категория мерчанта. Оставлен ради обратной совместимости — за MCC берите `merchantMcc`
`reason`	Причина отклонения (для `failed`)
`transactionTime`	Время операции по мнению эквайера
`syncedAt`	Когда мы подтянули запись с эквайера

Сумма в валюте мерчанта

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

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

То есть чек был на 910 ₺, а с карты списали 19.62 $. У операций, где конвертации не было (пополнение, закрытие карты), оба поля — null.

Выгрузка в CSV

GET /cards/transactions.csv?from=2026-08-01&to=2026-08-14
GET /cards/:id/transactions.csv?from=2026-08-01&to=2026-08-14

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

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.

В колонке mcc — тот же merchantMcc, что и в JSON; у операций без MCC она пустая.

amount со знаком: минус — деньги ушли с карты. У пополнения amount — это то, что пришло на карту (USD), а debitUsdt — то, что реально списалось с баланса компании (сумма + комиссия).

Real-time через webhook

Событие card.transaction.created приходит как только мы увидели новую транзакцию в выборке моста (обычно задержка 15–60 секунд от реальной операции).

{
  "event": "card.transaction.created",
  "data": { /* полный CardTransaction */ }
}

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

Платёж приходит двумя строками: сначала авторизация (statusName: Unposted), затем — в среднем через 29 часов — её проведение отдельной строкой с новым processorBillId и тем же upayParentId. На вторую приходит card.transaction.settled, а не ещё один created.

Связывайте их по upayParentId, иначе один платёж посчитается дважды. В выдаче GET /cards/:id/transactions мы схлопываем такую пару сами и показываем только финальную строку.

:::

Пагинация

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