Changelog

Все значимые изменения API документируются на этой странице.

• MCC мерчанта в операциях: у транзакций появилось поле merchantMcc — код категории торговой точки (5734, 5816, 4121, …), как его прислал эквайер. Приходит и в GET /cards/{id}/transactions, и в общем GET /cards/transactions.

  Поле есть примерно у трети операций — у покупок, где эквайер передал MCC. У пополнений, закрытий карты и части покупок будет null, поэтому рассчитывать на его наличие в каждой строке не стоит.

• В колонке mcc выгрузки GET /cards/transactions.csv теперь действительно MCC. Раньше туда попадал ditchCode, а это канал эквайринга — у всех операций там одно и то же значение (straitsx), к категории мерчанта отношения не имеющее.

• Описание ditchCode в документации исправлено: это не MCC. Поле осталось на месте ради обратной совместимости, но за категорией мерчанта теперь нужно идти в merchantMcc.

• Отмена заявки на карту: POST /cards/requests/{id}/cancel. Пока карта по заявке не выпущена, заявку можно отменить — резерв (cardOpeningFeeUsdt + cardMinInitialDepositUsdt) возвращается в доступный баланс, а externalId заявки снова освобождается.

  Только для статуса pending: выпущенную карту не отменяют, её закрывают через POST /cards/{id}/retire — иначе придёт CARD_REQUEST_NOT_CANCELABLE. Повторный вызов возвращает ту же заявку и ничего не меняет, поэтому запрос безопасно повторять, если ответ не дошёл.

• Новый webhook card.request_cancelled — заявку отменила наша сторона, резерв вернулся на баланс. На вашу собственную отмену события нет: результат приходит в ответе на сам запрос.

• Коды ошибок: CARD_REQUEST_NOT_CANCELABLE.

Обратная сторона приёма по QR: вы создаёте заявку с реквизитом получателя, мы списываем USDT с баланса и передаём заявку исполнителю, который отправляет рубли на карту или по номеру телефона через СБП.

• GET /payouts/config — лимиты, курс, часы приёма, подключены ли выплаты.
• GET /payouts/banks — справочник банков СБП; id оттуда идёт в bankId.
• POST /payouts/quote — сколько USDT спишется, без создания заявки.
• POST /payouts — создать заявку. Передавайте Idempotency-Key: ретрай с тем же ключом вернёт ту же заявку, а не выплатит второй раз.
• GET /payouts, GET /payouts/{id} — список и статус; ?search= ищет по вашему externalId или по нашему id.
• POST /payouts/{id}/cancel — отмена, пока заявку не взял исполнитель.
• POST /payouts/{id}/dispute — спор с вложениями (multipart, до 3 файлов).

Списание происходит при создании заявки, а не при исполнении: иначе заявка могла бы жить у исполнителя без списания. Провал возвращает средства автоматически и ровно один раз — признаком служит поле refundedAt.

Комиссия зашита в курс, отдельной строкой её нет. Курс фиксируется при создании заявки, движение рынка после этого на выплату не влияет.

Ограничения, о которых стоит знать заранее: приём заявок только в рабочие часы (по умолчанию 08:00–22:00 МСК, см. withinWorkingHours), одна выплата на пару «номер телефона + банк» раз в 72 часа и лимит одновременно активных заявок. Подробности — в разделе Выплаты в рублях.

Выплаты подключаются отдельно и по умолчанию выключены.

• payout.status_changed — на каждую смену статуса выплаты.
• payout.recharged — заявка вернулась в success после возврата средств, и сумма списана повторно. Отдельное событие потому, что из status этого не видно.

Добавлены PAYOUTS_NOT_ENABLED, PAYOUT_NOT_FOUND, PAYOUT_REQUISITE_INVALID, PAYOUT_BANK_REQUIRED, PAYOUT_BANK_UNKNOWN, PAYOUT_ACTIVE_LIMIT, PAYOUT_REQUISITE_COOLDOWN, PAYOUT_OUTSIDE_WORKING_HOURS, PAYOUT_NOT_CANCELABLE, PAYOUT_DISPUTE_NOT_ALLOWED, PAYOUT_SERVICE_REJECTED, PAYOUT_SERVICE_UNAVAILABLE.

Две последних различайте внимательно: PAYOUT_SERVICE_REJECTED — заявки нет и деньги вернулись, PAYOUT_SERVICE_UNAVAILABLE — заявка принята и средства не возвращены, повторять запрос можно только с тем же Idempotency-Key.

• Поиск ордера по идентификатору: GET /orders?search=.... Находит по вашему externalOrderId — достаточно части, поэтому 387057 найдёт transaction_387057 — либо по нашему id ордера, целиком или по первым символам. Полный UUID ищется точным совпадением.

• GET /disputes принимает search (по ордеру диспута — те же правила, что в /orders), resolution, limit и offset. Без limit поведение прежнее: вся история одним массивом. При постраничной выдаче общее число приходит в заголовке X-Total-Count.

Только документация — поведение API не менялось.

• refundAmount у диспутов описывался неверно. Было сказано, что поле заполняется только при partial_refund, а при полном refund равно null. На самом деле при refund в нём лежит полная сумма ордера; null бывает только при confirm. Если вы полагались на прежнее описание при сверке — перепроверьте логику.
• refundAmount — это не «зачислено на баланс». Поле показывает, какая часть ордера отменена. Если средства ещё не были списаны, решение по диспуту снимает заморозку, и баланс не растёт. Реальное движение — в истории баланса по referenceId = orderId.
• Исход диспута лежит в resolution, а не в status. Выигранный и проигранный диспут одинаково получают status: resolved; confirm означает отказ по диспуту. Добавлена таблица соответствия резолюции и итогового статуса ордера.
• Статус ордера после диспута. Было написано, что ордер остаётся disputed — на самом деле он переходит в failed при возврате и в success при отказе.
• Статусы in_review и rejected описывались как этапы рассмотрения. Они существуют в перечислении, но не выставляются — помечены как зарезервированные.

• Страница История баланса и эндпоинты GET /wallets/balance-history и GET /wallets/balance-history.csv в OpenAPI — раньше не были описаны нигде.
• В схему Dispute добавлен вложенный объект order: он всегда приходил в ответе, но в документации его не было, из-за чего за суммой ордера делали лишний запрос.

• Сумма в валюте мерчанта: у операций появились originalAmount и originalCurrency. Покупка на 910 ₺ теперь видна как таковая, а не только как списание 19.6248 USD. Поля есть и в выдаче, и в вебхуках операций; null там, где конвертации не было (пополнение, закрытие карты).
• Операции по всем картам сразу: GET /cards/transactions — одна лента по всем картам компании с фильтрами from/to, вместо запроса на каждую карту.
• Выгрузка в CSV: GET /cards/transactions.csv и GET /cards/:id/transactions.csv — операции и пополнения одним файлом (колонка type их различает), с фильтром по периоду.
• GET /cards/:id/transactions принимает from/to.

• card.status_changed — карта заморожена / заблокирована / деактивирована на стороне эквайера. Это не наш status карты: она остаётся assigned, будучи замороженной у эквайера.
• card.transaction.settled — ранее пришедшая авторизация провелась. Приходит отдельной строкой в среднем через 29 часов, с тем же upayParentId. Связывайте по нему, иначе один платёж посчитается дважды.

• GET /cards/:id/transactions отдавал в поле cardId внутренний идентификатор карты у эквайера — тот, который на вашей стороне получить неоткуда. Теперь там cardId карты в нашем API, как и в вебхуках.
• Некорректная дата в query-параметрах возвращает 400, а не 500.

• Закрытие карты: POST /cards/:id/retire теперь полноценно закрывает карту. Появились статусы closing → closed; остаток на карте за вычетом комиссии cardClosureFeeUsdt возвращается на баланс компании; отправляется новый webhook card.closed. См. Закрытие карты.
• Новый параметр компании cardClosureFeeUsdt — комиссия за закрытие карты, удерживается из возвращаемого остатка.

• POST /orders/prepare теперь принимает QR-ссылки от шести банков и автоматически нормализует их в формат qr.nspk.ru перед обработкой: Райффайзен, T-Bank/Тинькофф, Газпромбанк, ПСБ, UniCredit, Экспобанк. Прямые ссылки qr.nspk.ru, multiqr.ru и platiqr.ru работают как раньше. Дополнительно есть общий fallback на последний сегмент пути, совпадающий с паттерном qrcId (XX[A-Z0-9]{18,}).

• GET /rates/current — актуальный курс USDT/RUB. В ответе помимо rate/baseRate теперь приходят effectiveRate, offsetBps, minAmountRub, maxAmountRub. rate уже содержит per-company комиссию (см. ниже) — именно по нему создаётся следующий ордер.

• GET /cards/{id}/balance — live-баланс карты, проксируется в мост (~60-секундный кэш на стороне bridge). В cardsTestMode возвращает синтетический ответ.

Полная программа виртуальных VISA-карт с выпуском через API.

• POST /cards/request — выпуск (синхронный при наличии стока, иначе асинхронный с webhook card.assigned). Обязателен Idempotency-Key.
• GET /cards и GET /cards/{id} — список и детали карт компании.
• POST /cards/{id}/retire — закрытие карты.
• GET /cards/{id}/sensitive — одноразовое раскрытие полного номера и CVC (без кэша, логируется).
• GET /cards/{id}/otp/latest — последний 3DS OTP из почты эквайера.
• GET /cards/{id}/transactions — история операций по карте, cursor-пагинация через before.

• POST /cards/recharge/quote — расчёт totalDebitUsdt = userCharge + commission.
• POST /cards/recharge — выполнение пополнения (обязателен Idempotency-Key). Автоматический возврат средств при ошибке моста или при переходе в failed / refunded.
• GET /cards/recharges — история пополнений компании.

• card.assigned, card.otp_received, card.transaction.created, card.recharge.{succeeded,failed,refunded,in_progress_manual}.

• Раздел Карты в документации: обзор программы, выпуск, пополнение, PAN+CVC, 3DS OTP, история транзакций, webhooks.

• POST /orders/prepare — создание котировки из QR-кода СБП
• POST /orders/accept/{id} — подтверждение и создание ордера
• GET /orders — список ордеров с фильтрацией
• GET /orders/{id} — детали ордера
• Поддержка Idempotency-Key для accept

• POST /orders/{id}/disputes — открытие диспута
• GET /disputes — список диспутов компании

• GET /wallets — получение адреса кошелька компании
• GET /wallets/balance — баланс USDT и TRX
• GET /wallets/deposits — история депозитов

• POST /user-wallets — создание кошелька для пользователя
• GET /user-wallets — список кошельков
• GET /user-wallets/blocked — заблокированные кошельки
• POST /user-wallets/{id}/block — блокировка
• POST /user-wallets/{id}/replace — замена кошелька
• GET /user-wallets/deposits — депозиты пользователей

• События ордеров: order.status_changed
• События депозитов: deposit.created, deposit.completed, deposit.failed, deposit.aml_*
• HMAC-SHA256 подпись (X-Lumo-Signature)
• Автоматические ретраи (до 4 попыток)

• POST /auth/company/login — логин и получение API-ключа
• GET /auth/company/profile — профиль компании
• PATCH /auth/company/profile — обновление профиля
• POST /auth/company/regenerate-key — ротация ключа

• Аутентификация через X-API-Key
• IP Whitelist для доступа к API
• AML-проверки входящих депозитов

• SDK для JavaScript/TypeScript
• Расширенная аналитика в личном кабинете
• Поддержка дополнительных сетей (Solana, TON)

• GraphQL API
• Batch-операции