Оплата звёздами в Telegram-боте: как платить и как подключить приём звёзд

В ботах и мини-приложениях Telegram цифровые покупки оплачиваются звёздами — от игровых предметов до подписок на сервисы. Сначала разбираю оплату для покупателя: как платить и что делать, если товар не пришёл. Потом коротко — для владельца бота: как принимать звёзды и выводить их.

Как оплатить звёздами в боте или мини-приложении

Оплата звёздами в боте проходит в стандартном окне Telegram: вы видите товар, цену в звёздах и свой баланс, подтверждаете — и звёзды сразу уходят боту.

1. Выберите товар

   Бот пришлёт счёт с кнопкой оплаты, а мини-приложение само откроет окно оплаты.

2. Проверьте окно «Подтверждение покупки»

   Telegram спросит: «Вы точно хотите приобрести … у … за …?» Рядом показан ваш баланс звёзд.

3. Нажмите «Подтвердить и заплатить»

   Если звёзд не хватает, Telegram прямо в этом окне предложит их докупить.

4. Проверьте результат

   Появится «Спасибо за покупку», а операция — в истории «Моих звёзд».

Если бот продаёт подписку, окно будет другим: «Оформить подписку „…“ в … за … в месяц?». Такая оплата повторяется каждые 30 дней, пока вы не отмените продление, — подробно в статье о подписке за звёзды. Где взять звёзды на оплату, рассказано в гиде по звёздам Telegram.

Почему в ботах платят звёздами, а не рублями

В ботах и мини-приложениях цифровые товары и услуги продаются только за звёзды Telegram (Telegram Stars) — это прямое требование правил Telegram для разработчиков. Причина — правила App Store и Google Play: цифровые покупки внутри приложения должны идти через встроенные платежи магазинов.

• Цифровые товары — игровые предметы, доступ к функциям, контент, подписки — только звёзды. В документации у звёзд код валюты XTR.
• Физические товары — еда, одежда, всё, что доставляют курьером, — продаются за обычные деньги через сторонних платёжных провайдеров: картой, через Apple Pay или Google Pay. Звёздами за них не платят.

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

Если покупка не пришла: возврат и споры

Деньги за звёзды Telegram не возвращает, но звёзды за покупку в боте может вернуть разработчик. Порядок такой:

1. Напишите боту /paysupport. Отвечать на эту команду и разбирать вопросы об оплате обязан каждый бот и каждое мини-приложение. Если товар не выдан, разработчик может вернуть звёзды полностью и без штрафа для себя.
2. Если отказали — жалоба. Откройте операцию в «Моих звёздах», скопируйте «ID операции» и подайте жалобу через @BotFather — так описано в правилах звёзд.

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

Не пытайтесь вернуть деньги за сами звёзды через App Store или Google Play. В ответ Telegram может заморозить или списать звёзды, а с ними пропадёт и купленное. Все варианты возврата — в статье как вернуть звёзды в Telegram.

Ошибка «Bot pre-checkout timeout»

Ошибка Bot pre-checkout timeout значит, что бот не успел подтвердить заказ. По документации Telegram, после нажатия кнопки оплаты бот получает запрос pre_checkout_query и должен ответить на него за 10 секунд, иначе транзакция отменяется. Причина на стороне бота: например, его сервер перегружен или недоступен, или проверка заказа идёт слишком долго.

• Покупателю. Проверьте в «Моих звёздах», есть ли операция. Если её нет, повторите покупку через несколько минут. Если ошибка повторяется, напишите боту /paysupport или в поддержку мини-приложения — чинить это должен разработчик.
• Владельцу бота. Ответ answerPreCheckoutQuery должен уйти за 10 секунд, поэтому в обработчике оставьте только быструю проверку, можно ли выполнить заказ, а тяжёлые операции перенесите на этап после successful_payment: товар всё равно выдают только после него.

Как принимать оплату звёздами в своём боте

Приём звёзд в боте подключается через Bot API: отдельный платёжный провайдер не нужен, а схема оплаты состоит из четырёх шагов. Если бота у вас ещё нет, сначала создайте его в @BotFather — пошагово это описано в инструкции как создать бота в Telegram.

1. Выставьте счёт

   Методы sendInvoice или createInvoiceLink с валютой XTR и пустым provider_token. В списке цен для звёзд должна быть ровно одна позиция.

2. Подтвердите заказ за 10 секунд

   Перед списанием бот получает pre_checkout_query и должен ответить answerPreCheckoutQuery в течение 10 секунд, иначе оплата отменится.

3. Выдайте товар после оплаты

   Выдавайте товар только после сообщения successful_payment и сохраняйте telegram_payment_charge_id — он нужен для возврата.

4. Настройте поддержку

   Бот обязан отвечать на /paysupport. Вернуть звёзды можно методом refundStarPayment.

Ещё несколько возможностей Bot API:

• Подписки. Параметр subscription_period в счёте — сейчас только 2 592 000 секунд, то есть 30 дней; цена — до 10 000 звёзд. Отменить или вернуть продление у конкретного пользователя можно методом editUserStarSubscription.
• Учёт. Метод getMyStarBalance показывает баланс бота, getStarTransactions — историю операций.
• Тесты. Для проверки платежей у Telegram есть отдельная тестовая среда.

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

Сколько получает владелец бота и как вывести звёзды

Звёзды покупателей копятся на балансе бота, и владелец может обменять их через Fragment на GRAM или потратить на рекламу. Баланс виден в профиле бота, в разделе «Баланс». Там показаны «Доступный баланс», «Общий баланс» и «Всего поступлений», а также кнопки «Вывести через Fragment» и «Купить рекламу».

Условия на 3 октября 2026 года:

• вывод — через Fragment в GRAM (бывший TON), минимум 1000 звёзд;
• звёзды становятся доступны не раньше чем через 21 день после поступления;
• вознаграждение — $0,013 за звезду, а в Telegram Ads звезда засчитывается как $0,02 рекламного бюджета;
• выводить может только владелец бота с облачным паролем; если пароль или сеанс младше 24 часов, вывод не пройдёт;
• заработанные ботом звёзды действуют 3 года, потом списываются;
• если в боте включены темы в личных чатах, с каждой покупки за звёзды Telegram удерживает 15%.

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

Можно ли сделать свой бот-магазин звёзд

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

Что нужно учесть, если вы думаете о своём магазине:

• Fragment. Звёзды на нём покупают за криптовалюту с подключённого TON-кошелька, а Fragment может запросить проверку личности.
• Приём денег. Для оплаты картой нужен платёжный провайдер. У меня первый провайдер с оплатой по СБП заработал только через 22 дня.
• Закон. В России с 1 сентября 2026 года действует 282-ФЗ: он запрещает принимать криптовалюту в оплату товаров и услуг и распространять информацию о такой оплате.

Короткий чек-лист

Покупателю:

• платите только в окне Telegram «Подтверждение покупки»;
• проверьте, не подписка ли это с оплатой «в месяц»;
• товар не пришёл — /paysupport, при отказе — жалоба через @BotFather с ID операции;
• не оформляйте возврат за звёзды через магазин приложений.

Владельцу бота:

• счёт в валюте XTR, ответ на pre_checkout_query за 10 секунд, выдача после successful_payment;
• команда /paysupport обязательна, возвраты — через refundStarPayment;
• вывод — через Fragment от 1000 звёзд и через 21 день, по $0,013 за звезду.

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

---