# Webhooks по картам

Lumo отправляет следующие события на ваш `webhookUrl` в дополнение к
событиям ордеров (см. [Webhooks](/guides/webhooks)).

Все события подписаны одним `webhookSecret` компании, заголовок
`X-Lumo-Signature` (HMAC-SHA256 от JSON-тела).

## События

### `card.assigned`

Карта выпущена — приходит после асинхронного выпуска (когда исходный
вызов `POST /cards/request` вернул `status: pending`).

```json
{
  "event": "card.assigned",
  "data": {
    "cardId": "8c7f1823-...",
    "requestId": "2077f4ef-...",
    "maskedPan": "4466 ** ** 1234",
    "expiry": "03/29",
    "assignedAt": "2026-04-23T12:00:00Z"
  }
}
```

### `card.otp_received`

Получен 3DS-код из почты эквайера. См. [3DS OTP](/guides/cards/otp-3ds).

```json
{
  "event": "card.otp_received",
  "data": {
    "cardId": "8c7f1823-...",
    "code": "582130",
    "receivedAt": "2026-04-23T12:00:10Z",
    "expiresAt": "2026-04-23T12:02:10Z"
  }
}
```

### `card.transaction.created`

Новая транзакция по карте (purchase / refund / ...). Шейп — тот же, что
у `GET /cards/:id/transactions`.

### `card.closed`

Карта закрыта (см. [Закрытие карты](/guides/cards/close-card)). Остаток за
вычетом комиссии за закрытие возвращён на баланс компании.

```json
{
  "event": "card.closed",
  "data": {
    "cardId": "8c7f1823-...",
    "closingBalance": 24.5,
    "feeUsdt": 1,
    "refundUsdt": 23.5
  }
}
```

### `card.recharge.succeeded`

Пополнение успешно завершилось.

```json
{
  "event": "card.recharge.succeeded",
  "data": {
    "rechargeId": "7f2b12a4-...",
    "cardId": "8c7f1823-...",
    "targetAmountUsd": 50,
    "totalDebitUsdt": 51.96
  }
}
```

### `card.recharge.failed`

Отклонено эквайером. `totalDebitUsdt` автоматически возвращён на баланс.

```json
{
  "event": "card.recharge.failed",
  "data": {
    "rechargeId": "7f2b12a4-...",
    "cardId": "8c7f1823-...",
    "failureReason": "Insufficient issuer funds"
  }
}
```

### `card.recharge.refunded`

Успешное пополнение было позже возвращено (например, отменено
эквайером). Средства вернулись на баланс.

### `card.recharge.in_progress_manual`

Пополнение зависло — требуется ручное вмешательство нашей стороны.
Средства пока списаны. Связывайтесь с support с `rechargeId`.

## Гарантии доставки

- At-least-once: одно событие может прийти несколько раз.
- Используйте `data.cardId` / `data.rechargeId` как idempotency-ключ на
своей стороне.
- Порядок не гарантируется: `card.recharge.succeeded` может прийти
раньше соответствующего `card.transaction.created`, если эквайер быстрее
подтвердил пополнение, чем обновил историю.