Telegram Stars: внутренняя валюта для монетизации ботов

Заплатить в боте через карту — это пять экранов: ввод номера, CVC, 3-D Secure, редирект в банк, подтверждение. Каждый экран режет конверсию. А для разработчика из региона, где Stripe и PayPal не работают, первый экран вообще недоступен.

Stars (валютный код XTR) — внутренние деньги Telegram. Пользователь один раз пополняет звёздный баланс через App Store, Google Play или Fragment, а потом тратит их где угодно внутри мессенджера. Без карты. Без новых форм. Без третьих сторон между ботом и покупателем.

Для разработчика это значит примерно следующее: десять строк на Python — и бот умеет брать деньги. Не нужен эквайринг, не нужен PCI-сертификат, не нужен токен провайдера. Поле provider_token остаётся пустым, валюта указывается как XTR, и Telegram сам проводит транзакцию через свой контур.

Это не замена классическому эквайрингу — это параллельный слой для цифровых товаров. Комиссия ~30% при покупке через сторы кажется высокой, но она компенсируется тем, что каждый из 900+ миллионов пользователей Telegram уже потенциальный плательщик. Ни один сторонний платёжный шлюз не даст такого охвата.

Важно: Telegram требует использовать Stars для всех цифровых товаров и услуг в ботах — подписки, платный контент, генерации в AI, виртуальные предметы. Обычные провайдеры через Bot Payments API остаются только для физических товаров.

Дальше — маршрут денег от пользователя к боту, рабочий код на Python и Node.js, лимиты на момент июля 2026 и сценарии, в которых Stars работают или ломаются.

Что такое Stars

Звёзды — это предоплаченный баланс внутри Telegram. Пополнение происходит через встроенные покупки Apple или Google в мобильных клиентах. На десктопе и для крупных сумм работает @PremiumBot и Fragment — веб-платформа Telegram на блокчейне TON. После пополнения звёзды лежат на аккаунте и списываются при каждом действии в ботах, каналах и mini apps.

XTR — международный код валюты, как USD или EUR, но только для внутреннего использования Telegram. В Bot API передаётся в поле currency. Ключевое отличие от фиатных валют: provider_token не нужен, Telegram сам выступает процессингом.

Ориентировочный курс — 1 Star ≈ 0,013 USD. В App Store и Google Play звёзды дороже из-за наценки платформ. Через Fragment — дешевле, но не всем удобно пользоваться криптобиржей.

Что умеют Stars

Один вызов sendInvoice — это только поверхность. Stars покрывают весь спектр монетизации цифровых продуктов: разовые платежи, рекуррент, скрытый контент, донаты, подарки и даже реклама.

Возможность	Что даёт
Платежи в ботах (XTR)	sendInvoice с currency: XTR — пользователь платит звёздами в два тапа, не покидая чат
Подписки на Stars	Автоматическое списание раз в 30 дней. Подходит для закрытых каналов и премиум-функций
Paid media и paid posts	Контент в канале, который открывается после оплаты звёздами — фото, видео, файлы
Star reactions и tips	Донаты автору прямо в посте — звёзды как реакция вместо лайка
Gifts	Объекты с фиксированной ценой в звёздах. Лимитированные выпуски приобретают коллекционную ценность
Star Giveaways	Розыгрыш звёзд в канале — участники подписываются и бустят канал, автор получает охват
Refunds	refund_star_payment — возврат одной командой, без переписки с поддержкой Telegram
Баланс бота	Заработанные звёзды копятся на балансе. Вывод через Fragment в TON или трата внутри Telegram
Реклама со скидкой 30%	Звёзды с баланса бота можно направить на Telegram Ads — автоматическая скидка 30%

Как устроена экономика

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

Маршрут платежа

• Пополнение: пользователь докупает звёзды через Apple In-App Purchase, Google Play Billing или Fragment. На этом этапе Apple/Google берут свою стандартную комиссию (15–30%), если покупка через сторы.
• Списанием управляет Telegram. При покупке через сторы дополнительная комиссия платформы ~30% от стоимости звёзд. Через Fragment наценки сторов нет — только комиссия Fragment.
• Бот получает звёзды на внутренний баланс. Но не сразу: 21 день — период заморозки для антифрод-проверок. После разморозки баланс можно конвертировать в TON через Fragment, затем в фиат на бирже, либо потратить внутри Telegram — на рекламу, gifts или контент.

Инсайт: альтернатива через собственный эквайринг даёт больший процент с каждой транзакции. Но она отсекает аудиторию, которая не хочет вводить карту в незнакомом сервисе. В Telegram Stars конверсия выше за счёт нулевого барьера — и по итоговой выручке цифровые продукты чаще выигрывают.

Минимальный платёжный сценарий

Самый простой путь к деньгам в боте: sendInvoice с пустым provider_token и валютой XTR. Сумма — целое число звёзд, минимально 1. Пользователь видит нативный экран оплаты Telegram и подтверждает покупку в два тапа.

Python (python-telegram-bot)

from telegram import LabeledPrice

async def buy(update, context):
    await context.bot.send_invoice(
        chat_id=update.effective_chat.id,
        title="Premium доступ",
        description="30 дней безлимитных запросов к AI-боту",
        payload="premium_30d",  # ваш внутренний идентификатор заказа
        provider_token="",  # пусто = оплата в Stars
        currency="XTR",  # код валюты Stars
        prices=[LabeledPrice("Premium 30 дней", 500)]  # 500 Stars
    )

Node.js (Telegraf / GramIO)

bot.command("buy", async (ctx) => {
    await ctx.telegram.sendInvoice(ctx.chat.id, {
        title: "Premium доступ",
        description: "30 дней безлимитных запросов",
        payload: "premium_30d",
        provider_token: "",
        currency: "XTR",
        prices: [{ label: "Premium", amount: 500 }]
    });
});

payload — строка-идентификатор заказа, которую Telegram возвращает без изменений. Нужна для идемпотентности: если бот упал и перезапустился, по payload можно отличить новую покупку от повторной обработки уже выданного заказа.

Подтверждение оплаты

После sendInvoice Telegram присылает боту два апдейта. Пропустить любой — и платёж зависнет в воздухе: деньги списаны, товар не выдан.

• pre\_checkout\_query — предфинальная проверка. Бот должен ответить answerPreCheckoutQuery(ok=True) за 10 секунд. Если не успеть — Telegram отменяет операцию.
• successful\_payment — финал. Здесь выдаётся товар и сохраняется telegram\_payment\_charge\_id — без него возврат невозможен.

async def pre_checkout(update, context):
    await update.pre_checkout_query.answer(ok=True)

async def on_paid(update, context):
    payment = update.message.successful_payment
    # выдать доступ, записать в БД, отправить материал
    save_purchase(
        user_id=update.effective_user.id,
        charge_id=payment.telegram_payment_charge_id,
        stars=payment.total_amount,
        payload=payment.invoice_payload,
    )

Возврат платежа

refund_star_payment возвращает звёзды пользователю с баланса бота. Нужен только user_id и telegram_payment_charge_id из оригинальной транзакции.

await bot.refund_star_payment(
    user_id=user_id,
    telegram_payment_charge_id=charge_id
)

Внимание: Telegram требует, чтобы бот обрабатывал команду /paysupport и решал споры с пользователями самостоятельно. Без работающего /paysupport бот не пройдёт проверку при подключении цифровых товаров в @BotFather.

Подписки на Stars

Рекуррентный платёж в Stars — это createInvoiceLink с параметром subscription_period. Пока поддерживается единственное значение: 2592000 секунд, то есть 30 дней. Telegram сам списывает звёзды каждый месяц и шлёт боту событие продления или отмены.

link = await bot.create_invoice_link(
    title="Premium",
    description="Ежемесячный доступ",
    payload="premium_sub",
    provider_token="",
    currency="XTR",
    prices=[LabeledPrice("Premium / мес", 350)],
    subscription_period=2592000,  # 30 дней
)

Ссылку можно отправить в канале, в посте или повесить на inline-кнопку. Боту не нужно хранить таймеры продления — платформа делает это за вас. Но обработчик события отмены нужен: пользователь может отписаться в настройках Telegram в любой момент.

Совет: подписка в Stars — это не recurring-токен под вашим контролем. Пользователь отменяет через настройки Telegram, а не через вашего бота. База данных должна обрабатывать отмену так же надёжно, как продление — иначе доступ остаётся открытым после прекращения оплаты.

Gifts: подарки в Stars

Gifts — отдельный слой API внутри Stars. Это не перевод звёзд, а передача объекта: визуального подарка с фиксированной ценой, который отображается в профиле получателя. Для community-продуктов это инструмент поощрений и статуса.

• Отправка подарков — sendGift передаёт конкретный подарок от имени бота. Цена зафиксирована в звёздах, боту не нужно считать сумму.
• Получение подарков — бот принимает подарки от пользователей. Транзакции видны через getBusinessAccountGifts для бизнес-аккаунтов или через события gift в потоке апдейтов.
• Обратная конвертация — получатель превращает подарок обратно в звёзды и тратит их где угодно.
• Лимитированные выпуски — Telegram периодически выпускает коллекционные gifts ограниченным тиражом. Они работают как награды за активность и предметы для розыгрышей.

Сценарии, которые открывает Gifts: «спасибо автору», «подписчик месяца», «коллекционная награда за серию активностей». Всё это — без собственной валюты внутри продукта, на инфраструктуре Telegram.

Баланс бота и вывод

Бот накапливает звёзды на внутреннем балансе. Смотреть историю транзакций — getStarTransactions, текущий остаток — getMyStarBalance. Тот же баланс виден в @BotFather → ваш бот → Bot Settings → Payments → Stars Balance.

Три сценария траты

• Вывод во фиат — маршрут: баланс бота → TON через Fragment → биржа → фиат. Комиссии и лимиты Fragment указаны на их сайте.
• Реклама в Telegram — звёзды с баланса направляются на Telegram Ads с автоматической скидкой 30%. Для community-ботов: заработали — реинвестировали в рост.
• Внутренние операции — рефанды, отправка gifts, оплата контента в других ботах. Без вывода во внешний мир.

Внимание: 21-дневная заморозка между оплатой и выводом — обязательная антифрод-процедура. Обойти нельзя. Если кэшфлоу проекта чувствителен к трём неделям задержки, закладывайте этот лаг в модель до запуска.

Тарифы, лимиты и комиссии

Актуально на июль 2026. Telegram пересматривает цены периодически — сверяйтесь с Bot Payments API и changelog перед запуском.

Параметр	Значение
Минимальная сумма инвойса	1 Star
Максимум для подписок	10 000 Stars за период (~130 USD)
Максимум для paid media	25 000 Stars (~325 USD). Прежний потолок ~2 500 Stars устарел
Комиссия при покупке через сторы	~30% (наценка Apple/Google)
Комиссия через Fragment	Ниже, точный процент — на fragment.com
Период заморозки перед выводом	21 день с момента транзакции
Минимум для вывода	1 000 Stars
Период подписки	Строго 30 дней (2 592 000 секунд). Других вариантов нет
Лимит на период подписки	До 10 000 Stars
Таймаут ответа на pre_checkout_query	10 секунд
Окно для возврата	Жёсткого ограничения нет, рекомендуется решать споры в течение 21 дня
Тестовое окружение	Отдельный Telegram test environment с тестовыми звёздами

Практические сценарии

Три категории продуктов ложатся на Stars по-разному: AI-боты, контент и community. Для каждой — своя модель тарификации.

AI-боты

• Безлимит за подписку: 350–500 звёзд в месяц за неограниченные запросы. Базовые функции — бесплатно, но с дневным лимитом. Месячная подписка снимает ограничение.
• Pay-per-generation: 5–20 звёзд за одну генерацию — изображение, видео, длинный ответ. Подходит для тарификации дорогих моделей: пользователь платит за фактический расход, а не за абонент.
• Пакеты кредитов: 100 звёзд = 200 внутренних «токенов» бота. Удобно, когда себестоимость запроса непостоянна — пользователь сам выбирает, на что потратить кредиты.

Контентные продукты

• Разовый материал: paid media в канале или инвойс в боте. 50–300 звёзд за статью, PDF или видео — пользователь платит и сразу получает доступ.
• Закрытый канал: Stars-подписка на 30 дней, доступ через инвайт-ссылку с автоматическим истечением. Telegram сам списывает продление.
• Архив выпусков: разовая покупка 500–1000 звёзд за доступ ко всем предыдущим материалам. Работает как lifetime-доступ к базе.

Community-продукты

• Tips и star reactions: пользователи донатят автору или модератору за полезное сообщение — прямо в чате, без отдельной команды.
• Gifts за активность: бот ежемесячно отправляет подарок самому активному участнику. Оплата с баланса бота, награда — коллекционный объект в профиле.
• Платные бейджи: разовая покупка статуса или кастомной роли в чате. Цена в звёздах, выдача — навсегда или на период.
• Star Giveaways: автор канала разыгрывает звёзды среди подписчиков. Условие — подписка и буст канала. Органический рост аудитории за счёт платы автору.

Когда Stars не подходят

• Физические товары: доставка, склад, логистика — Stars не покрывают. Нужен классический Bot Payments API с провайдерами эквайринга.
• B2B-сделки: инвойсы, акты выполненных работ, НДС. Stars не генерируют бухгалтерских документов — транзакция во внутренней валюте платформы.
• Высокий средний чек: при цене выше ~30 USD комиссия сторов и потолок инвойса делают Stars невыгодными. Классический эквайринг даёт больше контроля и меньший процент на больших суммах.

Stars — это не платёжный шлюз, прикрученный к боту сбоку. Это платёжный слой самого Telegram, к которому бот получает доступ через десять строк кода. Чем меньше инфраструктуры между пользователем и оплатой — тем выше конверсия. Но чем меньше инфраструктуры — тем больше ответственности за идемпотентность, рефанды и обработку споров лежит на боте.

Ограничения

Ограничения

Заморозка 21 день — Между оплатой и выводом звёзд с баланса бота проходит 21 день — антифрод-окно Telegram.

Обойти нельзя. Если проект работает по модели «получил платёж → сразу выводит», финансовый контур будет отставать на три недели. Закладывайте этот лаг в кэшфлоу до запуска, а не после.

Комиссия сторов — При покупке звёзд через App Store и Google Play суммарная комиссия достигает ~30%.

Через Fragment она ниже, но Fragment требует криптокошелька и не подходит всем пользователям. Разница в доходе между каналами покупки — постоянный фактор, который бот не может выровнять.

Только 30 дней для подписок — Bot API принимает единственное значение subscription_period — 2592000 секунд.

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

Потолок инвойса — Подписки — до 10 000 звёзд (~130 USD).

Paid media — до 25 000 звёзд (~325 USD). Для продуктов с чеком выше этого диапазона Stars не подходят, нужен классический эквайринг через Bot Payments API.

Нет бухгалтерских документов — Транзакции в Stars — это переводы внутренней валюты Telegram, не фиатные платежи.

Нет чеков, счетов-фактур, актов. Для B2B сделок, где нужен НДС и закрывающие документы, Stars не работают.

Таймаут 10 секунд — На ответ pre_checkout_query у бота есть 10 секунд.

В high-load сценариях это ограничение требует отдельной очереди обработки, а не синхронного обращения к базе. Если бот не успевает — платёж отменяется автоматически.

Антипаттерны

Антипаттерны

Молчание на pre_checkout_query — Если бот не вызывает answerPreCheckoutQuery(ok=True) за 10 секунд, Telegram отменяет операцию.

Частая ошибка: обработчик повешен, но ответ не отправлен. Пользователь видит «оплата не прошла», доверие к боту падает, деньги не списались — но причина неочевидна ни пользователю, ни разработчику без логов.

Потерянный charge_id — telegram_payment_charge_id — единственный ключ для возврата.

Если не записать его в базу при successful_payment, рефанд становится невозможен без обращения в поддержку Telegram, и поддержка не гарантирует результат. Сохраняйте charge_id атомарно с выдачей товара.

Нет /paysupport — Telegram требует, чтобы бот обрабатывал /paysupport и решал споры.

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

Двойная выдача товара — Бот упал после оплаты, перезапустился, получил повторный successful_payment — и выдал товар дважды.

Идемпотентность по payload и charge_id обязательна: перед выдачей проверяйте, что этого charge_id ещё нет в базе.

Stars для физических товаров — Звёзды предназначены только для цифровых товаров.

Попытка продать физический товар через XTR-инвойс нарушает правила Telegram и может привести к блокировке платежей. Для физических товаров — Bot Payments API с провайдерами.

Чеклист

Чеклист

Цифровые товары в @BotFather — В @BotFather

→ ваш бот → Payments должны быть включены digital goods. Без этого sendInvoice с currency: “XTR” вернёт ошибку. Проверьте до написания кода — это настройка, а не код.

pre_checkout_query отвечает за 10 секунд — Обработчик должен вызывать answerPreCheckoutQuery(ok=True) в течение 10 секунд.

Если внутри есть обращение к базе или внешнему API — выносите в очередь, не блокируйте ответ.

successful_payment сохраняет charge_id — При успешной оплате запишите user_id, telegram_payment_charge_id, total_amount и invoice_payload в базу.

Без charge_id возврат невозможен.

Команда /paysupport работает — Отправьте /paysupport в бот вручную.

Ответ должен содержать понятный текст и контакт для споров. Если команда молчит — бот не пройдёт проверку в @BotFather.

Рефанд реализован — refund_star_payment должен быть доступен и работать.

Протестируйте в test environment: купите тестовый товар, верните деньги, проверьте баланс.

Идемпотентность по payload — Повторный successful_payment с тем же charge_id не должен выдать товар дважды.

Проверьте: отправьте дубль апдейта — бот должен проигнорировать или подтвердить, что заказ уже обработан.

Политика возвратов описана — Условия возврата пропишите в описании бота и в тексте инвойса.

Пользователь должен знать, что делать, если что-то пошло не так — до оплаты, а не после.

Тесты в test environment — Telegram предоставляет отдельное тестовое окружение с тестовыми звёздами.

Прогоните полный цикл: покупка → подтверждение → выдача → возврат. В прод — только после зелёного теста.

Мониторинг баланса — Настройте алерт на резкое падение звёздного баланса — это сигнал массовых рефандов или атаки.

getMyStarBalance можно опрашивать по расписанию.

Стратегия вывода — Заранее решите, куда выводить звёзды: Fragment

→ TON → фиат, Telegram Ads, или внутренние операции. Без плана звёзды зависнут на балансе на 21+ дней после каждой транзакции.

Ссылки

Ссылки

• Документация: Bot Payments API for Digital Goods (Telegram Stars)
• Документация: Полный справочник Bot API
• Документация: Описание валюты Stars на уровне MTProto
• Статья: Анонс Stars в блоге Telegram
• Сайт: Покупка и вывод Stars через Fragment
• Стандарт: Changelog Bot API

По теме

По теме

• База знаний: Очередь заявок в Telegram-боте: от FSM до inline-кнопок
• База знаний: Telegram-бот для бизнеса: точка входа, которая передаёт данные дальше