# Карты

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 отдаются по запросу,
ничего не кэшируется на нашей стороне.


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

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

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


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

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


```
requested  ──(assigned)──►  assigned  ──(retire)──►  retired
                               │
                               └──(processor error)──►  failed
```

| Статус | Значение |
|  --- | --- |
| `requested` | Заявка поставлена в очередь, карта будет выпущена позже |
| `assigned` | Активна, можно пополнять и использовать |
| `retired` | Закрыта компанией, пополнения запрещены |
| `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`.


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