# Карты

Lumo B2B выпускает виртуальные VISA-карты для ваших клиентов через
единый REST API. Никакого KYC от пользователя, никакой возни с
эквайером — просто HTTP-запрос и активная карта.

## Возможности

- **Выпуск**: одной командой `POST /cards/request`. Карта выдаётся из
нашего стока мгновенно, либо ставится в очередь и приезжает через
webhook.
- **3DS OTP**: SMS-коды забираются нами из почты эквайера и выдаются
через API — не нужно держать SIM-карту.
- **Пополнение**: `POST /cards/recharge` — списываем USDT с баланса
компании, пополняем карту.
- **Транзакции**: история по каждой карте через `GET /cards/:id/transactions`.
- **Чувствительные данные**: полный номер и CVC отдаются по запросу,
ничего не кэшируется на нашей стороне.
- **Закрытие**: `POST /cards/:id/retire` — карта закрывается, остаток за
вычетом комиссии за закрытие возвращается на баланс компании, приходит
webhook `card.closed`. См. [Закрытие карты](/guides/cards/close-card).


## Ценообразование

Параметры задаются администратором Lumo индивидуально под компанию:

| Параметр | Описание |
|  --- | --- |
| `cardOpeningFeeUsdt` | Фиксированная комиссия за выпуск карты (USDT) |
| `cardMinInitialDepositUsdt` | Минимальный первый депозит на карту (USDT) |
| `cardCommissionBps` | Наша комиссия за пополнение (bps: 100 = 1%) |
| `cardClosureFeeUsdt` | Комиссия за закрытие карты (USDT), удерживается из возвращаемого остатка |
| `cardsEnabled` | Включена ли программа карт для компании |


При `POST /cards/request` на балансе резервируется
`openingFee + minInitialDeposit`. При фактической выдаче `openingFee`
списывается, а `minInitialDeposit` остаётся доступным для первого
пополнения.

## Жизненный цикл карты

```
requested ─(assigned)─► assigned ─(POST /retire)─► closing ──► closed
                           │
                           └─(processor error)─► failed
```

| Статус | Значение |
|  --- | --- |
| `requested` | Заявка поставлена в очередь, карта будет выпущена позже |
| `assigned` | Активна, можно пополнять и использовать |
| `closing` | Запрошено закрытие, идёт обработка; пополнения уже запрещены |
| `closed` | Закрыта; остаток за вычетом комиссии возвращён на баланс компании |
| `retired` | Устаревший статус закрытых карт (эквивалентен `closed`) |
| `failed` | Эквайер не смог выпустить, средства автоматически разморожены |


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

Если у компании выставлен `cardsTestMode = true`, все операции работают
без реальной выдачи:

- `POST /cards/request` возвращает карту с маской `4466********TEST` и
сроком `12/29`.
- `POST /cards/recharge` с суммой `0.01` симулирует `failed`, `0.02` —
`in_progress_manual`, остальные значения — `succeeded`.
- `GET /cards/:id/sensitive` возвращает `4111 1111 1111 1111 / 123`.
- `GET /cards/:id/otp/latest` возвращает фиксированный код `843903`.


Это позволяет писать интеграцию без расхода реального стока.