Telegram Stars для ботов — как принимать платежи во внутренней валюте Telegram

Telegram Stars (валютный код XTR) — внутренняя валюта Telegram для оплаты цифровых товаров и услуг прямо в ботах и mini apps. Это самый простой способ принимать деньги от пользователей Telegram: без Stripe, без эквайринга, без PCI-сертификации и без зависимости от санкционных ограничений конкретных платёжных провайдеров.

Что это такое

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

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

Основные возможности

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

• Пользователь покупает Stars через Apple In-App Purchase, Google Play Billing или через Fragment и @PremiumBot (на десктопе и для крупных покупок).
• Курс плавающий, но в среднем держится в районе 1 Star ≈ 0,013 USD, то есть примерно 100 Stars ≈ 1,3 USD. Через Apple/Google курс выше из-за их комиссии, через Fragment — ниже.
• Telegram удерживает свою комиссию ~30% при покупке через сторы и меньше при покупке через Fragment.
• Бот получает Stars на свой внутренний баланс. Через 21 день после транзакции (анти-fraud окно) их можно вывести в TON через Fragment и далее в фиат, либо потратить внутри Telegram.

Интеграция: минимальный платёжный сценарий

Для приёма Stars не нужен provider_token — поле передаётся пустой строкой. Валюта — XTR, сумма — целое число Stars.

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 }]
  });
});

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

Telegram присылает два события — обработать нужно оба, иначе платёж зависнет:

1. pre_checkout_query — последний шанс отказать в оплате. Ответьте answerPreCheckoutQuery(ok=true) в течение 10 секунд.
2. 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,
    )

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

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

Рефанд возвращает Stars пользователю с баланса бота. Это обязательная функция: по правилам Telegram бот должен реагировать на команду /paysupport и решать споры самостоятельно.

Подписки на Stars

Подписка — это createInvoiceLink с дополнительным параметром subscription_period (значение в секундах, на момент написания поддерживается только 30 дней — 2592000).

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

Полученную ссылку публикуют в канале, в посте или в кнопке. После оплаты Telegram сам списывает Stars каждые 30 дней и отправляет боту событие об успешном продлении или отмене.

Gifts: подарки в Stars

Gifts — отдельный API внутри Stars, который полезен для community-продуктов.

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

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

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

Баланс смотрите через метод getStarTransactions (история) и getMyStarBalance. Доступ к балансу также есть в интерфейсе @BotFather → ваш бот → Bot Settings → Payments → Stars Balance.

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

1. Вывод в фиат через Fragment: бот → TON → биржа → фиат. Лимиты и комиссии Fragment описаны на их странице.
2. Покупка Telegram Ads прямо со Stars-баланса со скидкой 30%. Удобно для community-ботов: заработали — вложили в рост.
3. Внутренние операции: рефанды, gifts другим пользователям, оплата контента в других ботах.

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

Практические сценарии для контентных, community- и AI-продуктов

AI-боты

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

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

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

Community-продукты

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

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

• Продажа физических товаров и услуг → нужны провайдеры через обычный Bot Payments API.
• B2B-сценарии с инвойсами, актами и НДС → Stars не дают документов для бухгалтерии.
• Продукты с высоким средним чеком (>30 USD) — упираетесь в потолок инвойса и в комиссию сторов.

Чек-лист запуска Stars в боте

Ссылки

• Официальная документация: Bot Payments API for Digital Goods (Telegram Stars)
• Полный справочник Bot API: core.telegram.org/bots/api
• Описание валюты на уровне MTProto: core.telegram.org/api/stars
• Анонс Stars в блоге Telegram: telegram.org/blog/telegram-stars
• Покупка и вывод Stars через Fragment: fragment.com
• Тестовые покупки: @PremiumBot

По теме

• Статья: Делай, брат, делай! Два месяца pimenov.ai и что я понял про ИИ-агентов
• Блог: Люди + агенты в одном чате: как мы собрали рабочий контур в Telegram
• База знаний: Telegram Business Bots — как боты управляют бизнес-аккаунтом в Telegram

Если вы делаете контентный, community- или AI-продукт в Telegram и хотите спокойно встроить туда платежи и подписки на Stars — приходите на консультацию, разложим вашу модель по шагам и соберём минимальный рабочий контур, который не сломается на первой же оплате.