Промо-деньги в Cloud

Промо-деньги — это баланс, который мы начисляем Пространству, чтобы клиент мог оплатить им платный тариф или опубликованный пакет AI-кредитов либо инфраструктурных юнитов. Это деньги, а не единица расхода: у них есть валюта и сумма в её минорных единицах, есть срок действия, и они оплачивают точную цену, которую коммерческое ядро уже зафиксировало.

Это осознанно не наличные. Их нельзя вывести или перевести на другой аккаунт, а между реестрами промо-денег и юнитов нет свободного обмена. Флаг convertible: false означает именно это: клиент не должен придумывать курс или переводить произвольную сумму. При этом промо-деньгами можно оплатить опубликованный пакет юнитов — это точный коммерческий заказ с зафиксированной ценой, а не конвертация баланса.

Промо-деньги — это и не то же самое, что AI-кредиты или инфраструктурные юниты. Те метрят расход: одну операцию ИИ или одну единицу инфраструктурной работы, по зафиксированной версии цены. Деньги оплачивают точную цену и своей версии цены не имеют. Это два разных реестра, и в кабинете они показаны разными карточками.

Как начисляются промо-деньги

Есть два способа, и оба оставляют запись, по которой видно, кто и почему начислил.

Промокод. Оператор создаёт кампанию в разделе Консоль оператора → Лояльность и выбирает наградой Промо-деньги. Кампания задаёт три вещи, и все три обязательны:

валюту (трёхбуквенный код, например RUB);
сумму в минорных единицах этой валюты (например 250000 — это 2 500,00 ₽);
срок действия в днях — сколько деньги живут после начисления.

Эта же сумма является единицами бонуса кампании: одно число, один факт. Кампания, у которой два этих значения расходятся, отклоняется, а не выбирает молча одно из них.

Активируйте кампанию и передайте код клиенту. Когда он активирует код в кабинете, деньги начисляются неизменяемым лотом на промо-баланс его Пространства. Лот хранит, откуда он взялся (эта кампания), сколько в нём денег и когда они сгорают.

Оператор также может выпустить промокод «Пакет Team»: месяц Team на пять мест по цене, опубликованной при создании акции. Активируйте код в личном Пространстве. Он создаёт отдельный лот со сроком действия; обычный промо-баланс не увеличивается, и этим лотом нельзя оплатить Pro, AI-кредиты или другой пакет. При покупке Team выберите предложение по пакету и оплатите его этим лотом один раз. Карта и автопродление не нужны. Если цена Team потом изменится, лот сохранит обещанную цену, пока действующие условия рынка и юридические правила допускают продажу.

Решение оператора. Когда кампании нет — жест доброй воли, партнёрское соглашение, бета-программа — оператор корректирует баланс напрямую, в разделе Консоль оператора → Промо-деньги, под контролем двух человек. Один оператор предлагает сумму с кодом причины и слепком подтверждающих документов; другой оператор одобряет или отклоняет. Ничего не начисляется, пока второй оператор не одобрит, и отклонённое дело окончательно: его никогда не пересматривают.

То же правило двух человек распространяется и на списание. Возврат средств называет конкретный лот и может взять только то, что в нём ещё осталось: не деньги, которые клиент уже потратил, не деньги, удержанные под незавершённой оплатой, и не больше остатка лота.

Как промо-деньгами платят

При оплате тарифа клиент выбирает «Оплата из» → «Промо-баланс» вместо карты. В разделе Оплата → Пополнить баланс у каждого опубликованного пакета AI-кредитов или инфраструктурных юнитов отдельно доступна кнопка «Оплатить бонусами», если денег в выбранном Пространстве достаточно. Всё остальное — та же точная покупка: выбранный продукт, то же подтверждение и тот же контракт идемпотентности.

Оплата тарифа с промо-баланса покрывает один период и не включает автопродление. Переключатель автопродления показывается только при оплате картой. Прямой запрос к API с payment_source: "bonus" и auto_renew: true отклоняется с кодом bonus_renewal_unavailable до списания промо-денег. При покупке юнитов пакет зачисляется сразу после внутреннего списания бонусов: внешний платёжный заказ не создаётся и подтверждение банка не ожидается.

Если ранее начисленный баланс счёта покрывает всю стоимость покупки, выбранной как оплата картой, платёж картой и мандат на продление не создаются. Такая покупка тоже покрывает только один период; запрос с auto_renew: true отклоняется с кодом balance_renewal_unavailable до списания баланса. Выключите автопродление и купите следующий период после окончания текущего оплаченного периода: новая покупка того же Pro или Pro+ раньше времени отклоняется с кодом same_plan_period_active, чтобы остаток оплаченных дней не пропал. При частичном покрытии остаток можно оплатить картой и сохранить мандат.

В истории пополнений указан источник оплаты. У пакета, оплаченного с промо-баланса, есть внутренняя квитанция реестра вместо фискального чека платёжного провайдера. Квитанция называет точное завершённое удержание бонусов, созданный им лот кошелька юнитов, списанную сумму, валюту и число зачисленных юнитов. Она остаётся доступной при открытии покупки из истории. Если внутреннюю квитанцию прочитать не удалось, кабинет сообщает о её недоступности, а не называет её фискальным чеком, который ещё формируется.

Промо-деньги оплачивают всю цену целиком или ничего. Частичного применения нет, и это правило коммерческого реестра: зафиксированный платёж обязан в точности равняться зафиксированной сумме заказа. Заказ, наполовину оплаченный бонусом и наполовину картой, означал бы два источника денег на один заказ, чего учёт, споры и фискальные документы не выражают.

Когда баланса не хватает на всю цену, оплата отклоняется, и клиенту показывают точные цифры:

точную цену тарифа или пакета юнитов,
сколько лежит на промо-балансе,
сколько не хватает.

Они появляются рядом с кнопками покупки тарифа: после отказа не нужно искать их в разделе «Использование».

Если оплата картой включена, кабинет предложит её вместо бонусов. В бете только с бонусами нужно пополнить промо-баланс кодом или обратиться в поддержку. Ничего не списано, ничего не зарезервировано, баланс не тронут.

Если в момент расчёта баланса хватало, но другая оплата потратила его раньше, чем деньги успели удержать, вторая оплата отклоняется с тем же отказом. Клиента никогда не списывают неожиданно.

Срок действия

У каждого начисления свой срок, и он виден в выписке. Сгоревшие деньги не были потрачены и не входят в доступный баланс; карточка баланса показывает их отдельно, чтобы ничего не исчезало молча. Выписка показывает ближайшую сгорающую сумму и её дату, чтобы клиент успел ей воспользоваться.

Храните промокод до момента, когда он понадобится: отсчёт срока начинается при активации кода, а не при создании кампании.

Выписки

Оплата → Выписка по промо-деньгам перечисляет каждое движение: начисление, удержание, списание, снятие удержания, возврат денег на баланс, сгорание и любое списание решением оператора. Каждая строка называет движение и сумму, а строка, привязанная к лоту, показывает, когда эти деньги сгорят.

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

При переключении Пространства кабинет очищает прежний баланс и загружает баланс выбранного Пространства. Если прочитать баланс не удалось, кабинет показывает недоступность данных, а не ноль. В разделе Использование → Лимит трат дождитесь загрузки актуального лимита выбранного кошелька, прежде чем сохранять изменение. Если во время подтверждения лимита переключить Пространство или кошелёк, изменение отменяется: проверьте выбор и отправьте форму снова. Такая же защита действует для покупок в ожидании подтверждения: они не переносятся в другое Пространство.

Возвраты

Промо-деньги не проходили через платёжного провайдера. В кабинете нет кнопки возврата; отменённый тариф работает до конца оплаченного периода. Если покупка вызывает спор, обратитесь в поддержку. Полный возврат периода Team, оплаченного бонусами, ждёт подтверждения режима чтения общего Пространства на сервере; при недоступности сервера заявка остаётся в ожидании, а бонусный баланс не меняется. После подтверждения каждый потраченный лот восстанавливается в личном Пространстве покупателя с исходным сроком действия. Новый срок не начинается: уже истёкшие деньги останутся просроченными. Частичный возврат бонусной оплаты Team недоступен. Другие бонусные покупки автоматически не возвращаются.

Справка для оператора

Все операторские действия с промо-деньгами находятся в разделе Консоль оператора → Промо-деньги и требуют подтверждения (step-up). Предложение, решение, начисление и списание — четыре отдельных действия, поэтому в журнале аудита видно, кто что сделал. Чтение использует одно право, изменяющие действия — другое, и выдаётся оно отдельно от управления акциями: оператор, который ведёт кампании, не получает тем самым возможность создавать тратимый баланс.

API для операторов, которые автоматизируют работу:

GET /api/v1/cloud/operator/bonus/lots?space_id=…&currency=… — лоты Пространства, включая нетронутый остаток, который можно списать.
GET /api/v1/cloud/operator/bonus/adjustments?space_id=… — очередь решений по одному Пространству.
POST /api/v1/cloud/operator/bonus/adjustments — предложить дело о начислении или списании.
POST /api/v1/cloud/operator/bonus/adjustments/{id}/decide — одобрить или отклонить, другим оператором.
POST /api/v1/cloud/operator/bonus/adjustments/{id}/grant — исполнить одобренное начисление и создать лот.
POST /api/v1/cloud/operator/bonus/adjustments/{id}/clawback — исполнить одобренное списание.

API для кабинета и для автоматизации на стороне клиента:

GET /api/v1/cloud/billing/bonus?currency=… — промо-баланс Пространства и первая страница его выписки.
POST /api/v1/cloud/subscriptions/checkout с "payment_source": "bonus" — оплатить тариф с промо-баланса. Если поле не передано или передано "card", используется обычный путь оплаты. Ручные счета поле не принимают: банковский перевод — это не оплата с промо-баланса.
POST /api/v1/cloud/billing/wallet-topups?workspace_id=… с опубликованным product_code и "payment_source": "bonus" — купить точный пакет AI-кредитов или инфраструктурных юнитов за промо-деньги. На этом пути не передавайте payment_method: способ внешней оплаты относится только к платёжному провайдеру.
GET /api/v1/cloud/billing/wallet-topups?workspace_id=… и GET /api/v1/cloud/billing/wallet-topups/{order_id}?workspace_id=… — прочитать источник и постоянную квитанцию прежнего пополнения. Покупки за бонусы возвращают payment_source: "bonus" и ledger_receipt, покупки через провайдера — payment_source: "card" и состояние фискального чека.
GET /api/v1/cloud/billing/status отдельно возвращает card_payments_enabled и bonus_payments_enabled. Старое поле payments_enabled означает лишь то, что сервис покупки тарифа установлен; оно не подтверждает, что на этой установке принимаются карточные платежи.

Запуск пополнения кошелька — интерактивное изменение денег и ledger со свежим
подтверждением checkout. Эта операция намеренно отсутствует в SDK, CLI и MCP.
Указанные REST-маршруты обслуживают кабинет и просмотр его квитанций; само их
наличие не разрешает автоматизировать расход промобаланса или списание через
провайдера с помощью повторно используемых клиентских учётных данных.

Используйте один ключ идемпотентности для одного точного источника и запроса. Точный повтор с тем же ключом возвращает ту же покупку, даже если она уже исчерпала промобаланс; повторного списания нет. Переход с промо-баланса на карту или обратно является другой попыткой покупки и требует нового ключа.