# Пополнение карты

Пополнение — двухфазное: сначала quote (расчёт стоимости), потом execute.

## 1. Запросить quote

```
POST /cards/recharge/quote
```

### Параметры

| Параметр | Тип | Описание |
|  --- | --- | --- |
| `cardId` | uuid | ID карты из `GET /cards` |
| `targetAmount` | number | Сумма, которая должна оказаться на карте (USD) |


### Пример

```bash
curl -X POST 'https://b2b.lumowallet.io/cards/recharge/quote' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "cardId": "8c7f1823-...", "targetAmount": 50 }'
```

### Ответ

```json
{
  "cardId": "8c7f1823-...",
  "targetAmount": 50,
  "processorFeeBps": 300,
  "processorGrossAmount": 51.55,
  "ourFeeBps": 80,
  "ourFee": 0.41,
  "userCharge": 51.55,
  "currency": "USDT",
  "commissionUsdt": 0.41,
  "totalDebitUsdt": 51.96
}
```

`totalDebitUsdt` — сколько будет списано с баланса компании.
`userCharge` — брутто-сумма (включает комиссию эквайера), которая попадёт
на карту после списания комиссии эквайера — т.е. ровно `targetAmount`.

Quote не блокирует средства и живёт только в момент запроса.

## 2. Выполнить пополнение

```
POST /cards/recharge
```

Заголовок `Idempotency-Key` **обязателен**.

### Пример

```bash
curl -X POST 'https://b2b.lumowallet.io/cards/recharge' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: 9f0dcd94-...' \
  -H 'Content-Type: application/json' \
  -d '{ "cardId": "8c7f1823-...", "targetAmount": 50 }'
```

### Ответ (сразу)

```json
{
  "id": "7f2b12a4-...",
  "cardId": "8c7f1823-...",
  "targetAmountUsd": 50,
  "userChargeUsdt": 51.55,
  "commissionUsdt": 0.41,
  "status": "pending",
  "failureReason": null,
  "createdAt": "2026-04-23T12:00:00Z"
}
```

Финальный статус приходит webhook'ом `card.recharge.*` или обновляется
в `GET /cards/recharges`.

## Статусы recharge

| Статус | Значение | Балансовая операция |
|  --- | --- | --- |
| `pending` | В обработке | Списано при запросе |
| `succeeded` | Успех — средства на карте | Остаётся списанным |
| `failed` | Отклонено эквайером | **Возврат** `totalDebitUsdt` на баланс |
| `refunded` | Возврат после успеха | **Возврат** `totalDebitUsdt` на баланс |
| `in_progress_manual` | Зависло — ручной разбор | Списано, разморозка вручную |


## Ошибки при execute

| HTTP | Код | Значение |
|  --- | --- | --- |
| 400 | `INSUFFICIENT_FUNDS` | Не хватает `availableBalance` на `totalDebitUsdt` |
| 400 | `CARD_RETIRED` / `CARD_FAILED` | Карта не принимает пополнения |
| 400 | — | Отсутствует `Idempotency-Key` |
| 422 | — | Карта ещё не активирована эквайером |


Если вызов эквайера упал — мы **автоматически возвращаем**
`totalDebitUsdt` на баланс и пробрасываем ошибку. Ретраить можно сразу
с тем же `Idempotency-Key`.

## История пополнений

```bash
curl 'https://b2b.lumowallet.io/cards/recharges?limit=50&before=2026-04-23T00:00:00Z' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Возвращает массив `CardRecharge[]` по всем картам компании. Cursor-
пагинация через `before` (ISO-дата). Для фильтрации по одной карте —
фильтруйте на своей стороне по `cardId`.