Оплата Telegram Stars: как подключить в боте и вывести деньги

Оплата Telegram Stars стала рабочим способом принимать деньги за цифровые товары и услуги прямо в боте или Mini App, без вывода пользователя на сторонний сайт и без ввода карты. Я подключал приём звёзд в нескольких aiogram-ботах для клиентов и сразу расскажу, как это устроено технически и, самое главное, куда потом деваются деньги, потому что вопрос вывода интересует всех в первую очередь.

Что такое Telegram Stars и что можно продать за звёзды

Stars, звёзды, это внутренняя валюта Telegram. Пользователь покупает их через приложение (на iOS и Android это встроенная покупка через магазин приложений, на десктопе и в Telegram Premium возможны другие способы оплаты) и тратит внутри платформы: на реакции в каналах, платные посты, подписки на контент и на товары и услуги в ботах и Mini Apps, которые подключили приём Stars через Bot API.

Для разработчика это означает, что не нужен отдельный платёжный шлюз и договор с банком-эквайером под конкретно эту продажу. Приём звёзд встроен в Bot API, платёж проходит внутри Telegram, а бот получает событие об успешной оплате и может сразу выдать доступ.

Оплата Stars рассчитана на цифровые товары и услуги внутри Telegram. На практике это:

• доступ к закрытому каналу или посту
• подписка на регулярный контент внутри бота
• дополнительные функции бота: расширенные лимиты, отключение рекламы, приоритетная обработка запросов
• консультация или разбор, если вся услуга оказывается через переписку или звонок внутри Telegram
• цифровые файлы: PDF, шаблоны, доступ к базе знаний

Что нельзя продать за Stars

Правила Telegram для разработчиков ботов требуют, чтобы за Stars продавались именно цифровые товары и услуги, используемые внутри приложения. Для физических товаров с доставкой (мерч, одежда, что угодно, что поедет через СДЭК) Stars не подходят по смыслу и по правилам, там остаётся обычный эквайринг: например, T‑Bank, подключённый к WooCommerce на сайте, или Робокасса в настройках платёжных систем Tilda.

Как подключить приём Stars в Telegram-боте

Технически всё крутится вокруг метода sendInvoice из Bot API с валютой XTR, это код валюты для звёзд. Для платежей в Stars поле provider_token оставляют пустым, отдельный эквайер не нужен, платёж обрабатывает сам Telegram.

Вот минимальный рабочий пример на aiogram 3.x:

from aiogram import F, Router
from aiogram.types import LabeledPrice, Message, PreCheckoutQuery

router = Router()

@router.message(F.text == "/buy")
async def buy(message: Message):
    await message.bot.send_invoice(
        chat_id=message.chat.id,
        title="Доступ к разделу",
        description="Открывает доступ к закрытому разделу бота на 30 дней",
        payload="access_30d",
        provider_token="",
        currency="XTR",
        prices=[LabeledPrice(label="Доступ на 30 дней", amount=50)],
    )

@router.pre_checkout_query()
async def pre_checkout(query: PreCheckoutQuery):
    await query.answer(ok=True)

@router.message(F.successful_payment)
async def on_paid(message: Message):
    payment = message.successful_payment
    charge_id = payment.telegram_payment_charge_id
    payload = payment.invoice_payload
    # тут выдаю доступ и сохраняю charge_id в базу для возможного возврата

Важные детали, на которых можно споткнуться:

• amount в LabeledPrice для Stars это целое число звёзд, не копейки и не центы, как для обычных валют
• на pre_checkout_query нужно ответить в течение 10 секунд, иначе Telegram отменит платёж
• telegram_payment_charge_id из successful_payment обязательно сохраняю в базу, без него не получится сделать возврат через refundStarPayment, если пользователь попросит

Есть нюанс с инфраструктурой: aiogram-бот это постоянно работающий Python-процесс, а не обработчик, который дёргается по запросу, как PHP-скрипт на обычном хостинге сайта. Под него нужен отдельный сервер (VPS), который придётся настраивать, обновлять и оплачивать ежемесячно, обычный хостинг сайта на Tilda или WordPress для этого не подойдёт. Если у клиента уже есть сайт и нужен ещё и бот с оплатой Stars, я обычно закладываю это как отдельный пункт в разработку Telegram-бота с оплатой звёздами, а не пытаюсь пристроить бота на хостинг сайта.

Чем Stars отличаются от обычного эквайринга

Разница не только в валюте расчётов, она в том, что можно продавать и куда попадают деньги.

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

Как вывести деньги с баланса Stars

Прямого вывода звёзд в рубли на счёт из самого Telegram нет. Работает это через Fragment (fragment.com), сервис, который Telegram использует для операций со звёздами и TON-адресами.

Порядок такой:

• подтверждаю владение ботом на Fragment, привязка идёт через Telegram-аккаунт, которому принадлежит бот в BotFather
• вывожу накопленные Stars с баланса бота в TON на криптокошелёк
• дальше TON нужно обменять на рубли через биржу или обменник, это уже отдельная операция вне Telegram

Здесь есть задержка: по условиям для разработчиков звёзды на балансе могут стать доступны не сразу, а в срок до 21 дня после получения, причина в документе названа технической. Отдельным пунктом Telegram оставляет за собой право временно удерживать или списывать звёзды с баланса при возвратах платежей и подозрении на злоупотребления. То есть 21 день это верхняя граница, а не гарантированный срок ожидания: планировать вывод стоит с запасом до трёх недель, но деньги могут стать доступны и раньше.

Второй момент, курс TON к рублю плавает, так что рублёвый эквивалент выручки на момент продажи и на момент обмена будет отличаться, фиксированного курса конвертации Stars в рубли Telegram не даёт.

Налоги, возвраты и другие практические моменты

Деньги, которые в итоге пришли на счёт после обмена TON на рубли, это доход, и его нужно показывать так же, как любую другую выручку, вне зависимости от того, что по пути они были в звёздах и криптовалюте. Я рекомендую клиентам заранее обсудить схему с бухгалтером или оформить самозанятость или ИП под этот поток, а не разбираться постфактум, когда уже накопилась сумма за несколько месяцев.

По возвратам: пользователь может запросить возврат оплаты Stars, для этого в Bot API есть метод refundStarPayment, ему нужен как раз тот telegram_payment_charge_id, который я сохраняю в обработчике successful_payment. Если бот выдал доступ до подтверждения оплаты или потерял payload, возврат сделать физически нечем, поэтому логирование каждой успешной оплаты в базу, а не только в памяти процесса, я считаю обязательным шагом, а не опциональным.

Из практики: если оплата Stars это одна из нескольких точек продаж (сайт, бот, канал), имеет смысл сводить все успешные платежи в одно место, например пробрасывать событие successful_payment вебхуком вن8n сценарий и уже там раскладывать по внутренней базе или CRM, размещённой на сервере в России, а не в зарубежном облачном сервисе, если там хранятся контакты покупателей.

Что выбрать: Stars, обычный эквайринг или оба варианта

Если продукт целиком живёт внутри Telegram (доступ к каналу, платные функции бота, консультации в переписке), Stars закрывают всё без отдельного договора с банком. Если в ассортименте есть физические товары или нужна оплата вне Telegram (на сайте, по ссылке в письме), без обычного эквайринга не обойтись, и тогда логичнее делать оба канала параллельно: Stars для цифровой части внутри бота, T‑Bank или Робокасса для сайта и доставки.

Я обычно смотрю на это так: если у клиента уже есть бот и он продаёт что-то нематериальное, подключение Stars занимает немного времени и не требует переговоров с банком. Если бота ещё нет, а оплата звёздами нужна с нуля вместе с логикой выдачи доступа и хранением истории платежей, это уже полноценная разработка, а не час работы программиста.

Условия и возможности Telegram меняются, поэтому перед запуском я уточняю их у самого сервиса.

Частые вопросы

Можно ли принять оплату Stars за физический товар с доставкой?

Нет, Stars рассчитаны на цифровые товары и услуги внутри Telegram, для физических товаров с доставкой, например через СДЭК, используется обычный эквайринг на сайте, а не звёзды.

Как быстро деньги от продажи за Stars оказываются на счёте?

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

Нужно ли оформлять ИП или самозанятость для приёма Stars?

Деньги, полученные после обмена TON на рубли, считаются доходом независимо от формы, в которой они прошли путь до счёта, поэтому оформление самозанятости или ИП под этот поток стоит обсудить с бухгалтером заранее, а не после того, как накопится сумма за несколько месяцев.

Что если пользователь попросит вернуть оплату?

Для этого в Bot API есть метод refundStarPayment, ему нужен telegram_payment_charge_id из события successful_payment. Если бот не сохраняет этот идентификатор в базу при каждой оплате, сделать возврат будет нечем.