Счёт в Telegram Stars (XTR) в боте: платёжный поток для разработчиков по шагам
Как продавать цифровой товар за Stars через бота: sendInvoice с валютой XTR, ответ на pre_checkout_query за 10 секунд, successful_payment, хранение charge_id, режимы пересылки и чек-лист запуска.
Опубликовано:

Ваш бот продаёт цифровое — подписку, контент, AI-запросы или игровые предметы? Тогда оплата только в Telegram Stars. Эта статья по шагам показывает поток счёта в Telegram Stars (XTR) глазами разработчика, по официальной документации Bot API. Почему именно Stars: цифровые товары в ботах только за Stars.
Поток с высоты
| Шаг | Что делает бот | Что присылает Telegram |
|---|---|---|
| 1 | sendInvoice, currency = XTR | — |
| 2 | Ждёт | pre_checkout_query |
| 3 | answerPreCheckoutQuery (за 10 секунд) | — |
| 4 | Ждёт | successful_payment |
| 5 | Сохраняет charge_id, выдаёт товар | — |
Шаг 1. Создать счёт
Два пути:
- Счёт от бота — метод sendInvoice. Товар цифровой, поэтому provider_token — пустая строка, а в поле валюты — XTR. Счёт можно отправить в личный чат, группу или канал.
- Inline-счёт — если бот поддерживает inline-режим, через inputInvoiceMessageContent пользователи делятся счётом с друзьями, в группах и каналах. Кнопка Pay у такого счёта многоразовая.
Шаг 2. Выбрать поведение при пересылке
Управляется параметром start_parameter:
- Мультичатовый счёт — у пересланных копий тоже есть кнопка Pay, платить могут многие. Inline-счета всегда такие.
- Одночатовый счёт — оплачивается только в чате, куда отправлен; у копий вместо Pay — кнопка с deep link на бота.
Важно: одночатовый счёт в личном чате с ботом оплачивается только один раз. В любом случае решать, принимать ли новый платёж, — боту.
Шаг 3. Pre-checkout
Пользователь (при необходимости докупив Stars) нажимает Pay. Бот получает pre_checkout_query с данными заказа и должен ответить answerPreCheckoutQuery в течение 10 секунд — иначе транзакция отменится. Если отказываете, объясните причину человеческим языком: Telegram покажет её пользователю.
Шаги 4–5. Оплата и выдача
При успешной оплате приходит successful_payment. Только после этого выдавайте товар — ответ на pre_checkout_query ещё не гарантирует оплату. Сохраните telegram_payment_charge_id: он нужен для возврата.
Перед запуском
- Включите двухэтапную проверку на аккаунте владельца бота.
- Условия по команде /terms, поддержка по /support и /paysupport.
- Будьте готовы к спорам и возвратам — refundStarPayment. Подробнее: возврат Stars и /paysupport.
- Стабильный сервер и резервные копии данных о платежах.
Как тестировать
В отдельной тестовой среде Telegram платежи в Stars тестируются бесплатно. Когда всё работает — переключаетесь на продакшн.
Сторона покупки Stars
Пользователи покупают Stars в приложении или через @PremiumBot, а PayStars продаёт их за USDT. Если вашему сервису нужно покупать Stars автоматически, помогут API PayStars и обзор API.
Частые вопросы
Можно принимать крипту или другую валюту вместо Stars?
Нет. Для цифровых товаров и услуг внутри приложений Telegram используются только Stars.
Как протестировать оплату?
Подключите бота к тестовой среде Telegram — там платежи в Stars тестируются бесплатно.
Как сделать возврат?
Методом refundStarPayment в Bot API.
Источники
Покупайте Stars и Premium за USD (USDT)
Через API-ключ: 0% (цена Fragment). Через сайт: 5%.
Другие новости
Политика возвратов для бота с Telegram Stars: шаблон и примерыЧто должна включать политика возвратов бота с Telegram Stars: условия, срок, /paysupport и refundStarPayment, а также пример текста, который можно адаптировать.Читать →
Что происходит с Telegram Stars, если вы потеряли доступ к аккаунтуStars принадлежат аккаунту Telegram, а не телефону. Узнайте, что с ними будет при потере доступа, как вернуть вход и как защитить свой баланс.Читать →
Учёт доходов в Telegram Stars для автора или бизнесаКак вести понятный учёт доходов в Telegram Stars: что записывать, как фиксировать вывод через Fragment, как отделить личное от бизнеса и что спросить у бухгалтера.Читать →