Webhooks по картам

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

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

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

• requestId — id заявки из того самого вызова; null, если карту выдали без заявки.
• externalId — значение, переданное при подаче заявки, или null, если не передавали.

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

Заявка на карту отменена, резерв под неё вернулся в доступный баланс.

{
  "event": "card.request_cancelled",
  "requestId": "2077f4ef-a03d-4001-82e3-1965e44036e8",
  "externalId": "user-42-card-1",
  "status": "cancelled",
  "createdAt": "2026-04-23T12:05:00Z"
}

Приходит, когда заявку отменили с нашей стороны. На вашу собственную отмену через POST /cards/requests/{id}/cancel события нет: результат вы уже получили в ответе на сам запрос.

Получен 3DS-код из почты эквайера. См. 3DS OTP.

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

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

{
  "event": "card.transaction.created",
  "data": {
    "cardId": "8c7f1823-...",
    "cardMaskedPan": "4466 ** ** 1234",
    "upayBillId": "88120394",
    "upayParentId": "77001122",
    "typeName": "Consumption",
    "statusName": "Unposted",
    "amount": "19.6248",
    "currency": "USD",
    "originalAmount": "910",
    "originalCurrency": "TRY",
    "merchantName": "CHURROS TIME CAFE TURIZM",
    "transactionTime": "2026-08-14T10:00:00Z"
  }
}

amount/currency — в валюте карты (USD). originalAmount/originalCurrency — сумма у мерчанта до конвертации: покупка на 910 ₺ придёт именно так. У операций без конвертации (пополнение, закрытие) обе — null.

Ранее пришедшая авторизация провелась (или была отменена). Эквайер присылает это отдельной строкой с новым upayBillId и тем же upayParentId — в среднем через 29 часов после авторизации.

:::warning Не считайте платёж дважды

created и settled — это один платёж, а не два. Связывайте их по upayParentId: приход settled означает, что соответствующая авторизация достигла финального статуса, а не что произошла новая покупка.

:::

Карта сменила состояние на стороне эквайера — заморожена, заблокирована, деактивирована.

{
  "event": "card.status_changed",
  "data": {
    "cardId": "8c7f1823-...",
    "cardMaskedPan": "4466 ** ** 1234",
    "upayState": 3,
    "upayStateName": "Frozen",
    "previousState": 1,
    "previousStateName": "Normal",
    "syncedAt": "2026-08-14T10:00:00Z"
  }
}

Состояния: 1 Normal, 2 Pending Activation, 3 Frozen, 4 Locked, 5 Deactivated, 7 Activating, 8 Locking, 9 Unlocking, 10 Deactivating, 13 Rejected, 14 Cancelled, 15 Replacing, 16 Replaced.

Это состояние не то же самое, что status карты в нашем API: там наш жизненный цикл (requested → assigned → closing → closed), и карта остаётся assigned, будучи замороженной у эквайера.

Карта закрыта (см. Закрытие карты). Остаток за вычетом комиссии за закрытие возвращён на баланс компании.

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

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

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

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

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

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

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

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