База знаний
Telegram Stars (XTR) — внутренняя валюта Telegram для оплаты цифровых товаров и услуг прямо в ботах. Разбираем, как устроены Stars, как принимать оплату через Bot API, как работают gifts, баланс бота, рефанды и какие сценарии монетизации это открывает для контентных, community- и AI-продуктов.
Telegram Stars (валютный код XTR) — внутренняя валюта Telegram для оплаты цифровых товаров и услуг прямо в ботах и mini apps. Это самый простой способ принимать деньги от пользователей Telegram: без Stripe, без эквайринга, без PCI-сертификации и без зависимости от санкционных ограничений конкретных платёжных провайдеров.
Telegram Stars — это виртуальная валюта внутри экосистемы Telegram. Пользователь покупает Stars один раз через встроенные покупки Apple/Google или через @PremiumBot, а потом тратит их в ботах, каналах и mini apps без новых подтверждений и ввода карты.
Для разработчика это означает одно: вы можете брать деньги за цифровой контент с любого пользователя Telegram, написав примерно десять строк кода. Никакой инфраструктуры платежей.
| Возможность | Что это даёт |
| Платежи в ботах (XTR) | Один вызов sendInvoice с currency: "XTR" — и пользователь оплачивает Stars за пару тапов |
| Подписки на Stars | Рекуррентные платежи раз в 30 дней. Можно продавать доступ к закрытому каналу или к премиум-функциям бота |
| Paid media и paid posts | Скрытые фото/видео, которые открываются после оплаты Stars прямо в чате |
| Star reactions и tips | Пользователи отправляют Stars автору поста как реакцию или донат |
| Gifts | Подарки в Stars между пользователями и от пользователей к боту/каналу. Часть подарков — лимитированные, с коллекционной ценностью |
| Star Giveaways | Розыгрыши Stars в каналах в обмен на буст и подписку |
| Refunds | Возврат покупки одной командой Bot API без обращения в поддержку Telegram |
| Баланс бота | Stars копятся на балансе бота, их можно вывести в фиат или потратить внутри Telegram |
| Реклама со скидкой 30% | Stars с баланса бота можно тратить на Telegram Ads с автоматической скидкой 30% |
Для приёма Stars не нужен provider_token — поле передаётся пустой строкой. Валюта — XTR, сумма — целое число Stars.
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
)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 присылает два события — обработать нужно оба, иначе платёж зависнет:
pre_checkout_query — последний шанс отказать в оплате. Ответьте answerPreCheckoutQuery(ok=true) в течение 10 секунд.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 и решать споры самостоятельно.
Подписка — это 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 — отдельный API внутри Stars, который полезен для community-продуктов.
sendGift отправляет конкретный подарок (с заранее заданной ценой в Stars) от имени бота получателю.getBusinessAccountGifts (для бизнес-аккаунтов) или через события gift в апдейтах.Для контентных и community-проектов это позволяет строить сценарии «спасибо автору», «подарок подписчику месяца», «коллекционные награды за активность» без отдельной валюты внутри продукта.
Баланс смотрите через метод getStarTransactions (история) и getMyStarBalance. Доступ к балансу также есть в интерфейсе @BotFather → ваш бот → Bot Settings → Payments → Stars Balance.
Три сценария трат:
| Параметр | Значение |
| Минимальная сумма инвойса | 1 Star |
| Максимальная сумма инвойса | 2 500 Stars (ориентировочно ~32 USD на момент написания) |
| Комиссия Telegram | ~30% при покупке через App Store / Google Play, ниже через Fragment |
| Окно вывода | 21 день после транзакции |
| Период подписки | Только 30 дней (2 592 000 секунд) |
| Срок ответа на pre_checkout_query | 10 секунд |
| Окно рефанда | Нет жёсткого ограничения, но рекомендуется решать споры в течение 21 дня |
| Тестовое окружение | Отдельный Telegram test environment с тестовыми Stars |
Если вы делаете контентный, community- или AI-продукт в Telegram и хотите спокойно встроить туда платежи и подписки на Stars — приходите на консультацию, разложим вашу модель по шагам и соберём минимальный рабочий контур, который не сломается на первой же оплате.