Оплата Telegram Stars в боте: как подключить, вернуть платёж и вывести звёзды

Когда нужны Stars, а когда обычная оплата

• Stars обязательны для цифровых товаров и услуг, которые потребляются внутри Telegram: доступ к материалам, курсы, подписка на закрытый канал, функции бота, цифровые файлы. Так требуют правила Telegram для разработчиков ботов.
• Обычная оплата (карты, ЮKassa) — для физических товаров и офлайн-услуг: доставка, запись в салон, консультация вживую. Подробнее: ЮKassa в Telegram-боте.

Сравнение всех способов: приём оплат в Telegram-боте.

Как проходит платёж

1. Бот выставляет счёт методом sendInvoice (или создаёт ссылку createInvoiceLink): валюта XTR, provider_token пустой, цена — одна позиция в звёздах.
2. Telegram присылает pre_checkout_query. Бот должен ответить answerPreCheckoutQuery в течение 10 секунд: подтвердить, что товар доступен.
3. После оплаты приходит successful_payment с идентификатором платежа telegram_payment_charge_id. Только после этого бот выдаёт товар.
4. Сохраните идентификатор платежа — без него не сделать возврат.

Пример на aiogram 3

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

@router.message(F.text == "/buy")
async def buy(message: Message):
    await message.answer_invoice(
        title="Доступ к урокам",
        description="Месяц доступа к закрытому разделу",
        payload="lessons_30d",
        currency="XTR",
        prices=[LabeledPrice(label="Доступ", amount=250)],
    )

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

@router.message(F.successful_payment)
async def paid(message: Message):
    charge_id = message.successful_payment.telegram_payment_charge_id
    await save_payment(message.from_user.id, charge_id)
    await grant_access(message.from_user.id)

В aiogram 3 параметр provider_token для звёзд можно не передавать. Сумма указывается в целых звёздах.

Возвраты

Возврат делается методом refundStarPayment с ID пользователя и telegram_payment_charge_id. Правила Telegram требуют, чтобы у бота была поддержка покупателей: команда /paysupport и понятный способ решить спор. Если покупатель не получил товар, а вы не отвечаете, Telegram может вмешаться сам.

Подписки

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

Как вывести звёзды

• Звёзды, полученные ботом, становятся доступны для вывода через 21 день после получения.
• Минимальная сумма вывода — 1 000 Stars.
• Вывод — через платформу Fragment, в криптовалюте TON. Дальше TON нужно продать, и это отдельный вопрос налогов и законодательства в вашей стране.
• Звёздами на балансе бота можно также оплачивать рекламу в Telegram.

Частые ошибки

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

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