Перейти к содержимому
Последнее обновление

Карты

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

Возможности

  • Выпуск: одной командой POST /cards/request. Карта выдаётся из нашего стока мгновенно, либо ставится в очередь и приезжает через webhook.
  • 3DS OTP: коды подтверждения покупок мы получаем из почты эквайера и отдаём через API и вебхук — не нужно держать SIM-карту.
  • Пополнение: POST /cards/recharge — списываем USDT с баланса компании, пополняем карту.
  • Баланс: по одной карте — GET /cards/:id/balance, по выбранным — POST /cards/balances/query, по всем сразу — GET /cards/balances.
  • Транзакции: история по каждой карте через GET /cards/:id/transactions или по всем сразу через GET /cards/transactions, с фильтром по периоду и выгрузкой в CSV. Видно и сумму у мерчанта до конвертации.
  • Реквизиты карты: полный номер и CVC отдаются по отдельному запросу и только участникам с правом cards.sensitive.
  • Закрытие: POST /cards/:id/retire — карта закрывается, остаток за вычетом комиссии за закрытие возвращается на баланс компании, приходит webhook card.closed. См. Закрытие карты.

Эндпоинты карт работают, только если программа карт подключена компании, — иначе 403 CARDS_NOT_ENABLED. Права для каждого эндпоинта — в разделе Команда и права.

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

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

ПараметрОписание
cardOpeningFeeUsdtФиксированная комиссия за выпуск карты (USDT)
cardMinInitialDepositUsdtСумма, которую нужно держать на балансе сверх комиссии при подаче заявки (USDT)
cardCommissionBpsНаша комиссия за пополнение (bps: 100 = 1%). Ставку, по которой считается конкретное пополнение, возвращает quote в ourFeeBps — ориентируйтесь на неё
cardMinRechargeUsdtМинимальная сумма одного пополнения для компании; если не задана — действует общий минимум 10
cardClosureFeeUsdtКомиссия за закрытие карты (USDT), удерживается из возвращаемого остатка
cardsEnabledВключена ли программа карт для компании

Условия своей компании видно в GET /auth/company/profile, в блоке cards (кроме комиссии за закрытие — её фактическое значение приходит в feeUsdt вебхука card.closed):

{
  "cards": {
    "enabled": true,
    "openingFeeUsdt": 5,
    "commissionBps": 80,
    "minInitialDepositUsdt": 10,
    "minRechargeUsdt": null,
    "testMode": false
  }
}

При POST /cards/request на балансе резервируется openingFee + minInitialDeposit. Когда карта выдана, резерв снимается целиком: openingFee списывается с баланса, а minInitialDeposit возвращается в доступный баланс — отдельно под первое пополнение он не закрепляется.

Жизненный цикл

Пока карта не выдана, существует только заявка на неё:

Статус заявкиЗначение
pendingЗаявка в очереди, резерв заморожен
fulfilledКарта выдана, в заявке заполнен cardId
cancelledЗаявка отменена, резерв возвращён

Карта появляется в API в момент выдачи — сразу в статусе assigned:

assigned ─(POST /retire)─► closing ──► closed
Статус картыЗначение
assignedАктивна, можно пополнять и использовать
closingЗапрошено закрытие, идёт обработка; пополнения уже запрещены
closedЗакрыта; остаток за вычетом комиссии возвращён на баланс компании
retiredУстаревший статус закрытых карт (эквивалентен closed)

Если карта надолго остаётся в closing, напишите в поддержку.

Значения requested и failed для карты и failed для заявки есть в перечислениях, но текущая версия API их не выставляет.

Состояние у эквайера

Помимо нашего статуса у карты есть состояние на стороне эквайера — upayState / upayStateName в GET /cards и GET /cards/{id}: Normal, Frozen, Locked, Deactivated и другие (полный список — в Webhooks по картам). Карта может оставаться assigned, будучи замороженной у эквайера, — пополнения по ней тогда отклоняются. Если состояние получить не удалось, поля приходят null.

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

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

  • POST /cards/request сразу возвращает карту с маской 4466********TEST и сроком 12/29; вебхук card.assigned не отправляется.
  • POST /cards/recharge сразу завершается со статусом succeeded.
  • GET /cards/:id/sensitive возвращает 4111 1111 1111 1111 / 123.
  • GET /cards/:id/otp/latest возвращает фиксированный код 843903.
  • GET /cards/:id/balance, GET /cards/balances и POST /cards/balances/query возвращают 123.45 USD.
  • POST /cards/:id/retire закрывает карту сразу, как будто на ней было 123.45.
  • Истории операций нет: GET /cards/transactions и GET /cards/:id/transactions возвращают пустой список.

Деньги с баланса при этом списываются и возвращаются по-настоящему: комиссия за выпуск, пополнения и возврат при закрытии проходят через баланс компании.

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

История баланса

Выпуск карты