Telegram Stars: что это и как принимать оплату в боте

Telegram Stars — это внутренняя цифровая валюта Telegram: пользователь покупает Stars и платит ими за цифровые товары и услуги в боте или Mini App. Подписка, премиум-функции, доступ к контенту, предметы в игре — всё это продаётся за Stars.

Главное: по правилам Telegram цифровые товары и услуги внутри Telegram должны продаваться только за Stars. Это требование связано с правилами App Store и Google Play. Для физических товаров и офлайн-услуг обычная оплата через Click, Payme и других провайдеров продолжает работать.

Ниже разберём, как устроены Stars, как подключить оплату в боте, как Stars «переводятся» в сумы и когда нужны не Stars, а Click.

Telegram Stars: что это и зачем

Раньше владельцы ботов могли продавать цифровые товары через разных платёжных провайдеров. Но Apple и Google требуют, чтобы цифровые товары в приложениях из их магазинов продавались через встроенные покупки. Telegram решил это через Stars: пользователь покупает Stars встроенной покупкой в приложении, а потом тратит их в ботах.

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

Цифровой или физический товар

Бывают пограничные случаи. Если продукт смешанный, например курс с онлайн- и офлайн-частью, как его продавать, нужно определить по правилам Telegram ещё до запуска.

Как работает оплата Stars в боте

Технически оплата Stars похожа на обычный платёжный поток Telegram Bot API, но с несколькими отличиями:

1. Создание счёта. Бот отправляет счёт через sendInvoice или createInvoiceLink. Валюта — XTR, токен провайдера для цифровых товаров оставляют пустым.
2. Предварительная проверка. Когда пользователь нажимает «Оплатить», бот получает pre_checkout_query и должен ответить на него в течение 10 секунд, иначе транзакция отменяется.
3. Подтверждение оплаты. Товар выдаётся только после сообщения successful_payment. Ответ на предварительную проверку ещё не означает, что оплата прошла.
4. Сохранение идентификатора. Идентификатор платежа — telegram_payment_charge_id — нужно сохранить в базе, он понадобится для возврата.

Возвраты и поддержка

Для возврата Stars используется метод refundStarPayment. Telegram требует, чтобы бот отвечал на команду paysupport и своевременно обрабатывал обращения по оплате. Перед запуском также рекомендуется добавить команды с условиями использования и поддержкой.

Оплата в Telegram Mini App

Mini App — это веб-приложение, которое открывается внутри Telegram. Правило то же: цифровые товары — за Stars, физические — через обычных провайдеров. Mini App открывает ссылку на счёт и показывает пользователю стандартное платёжное окно Telegram, а результат приходит на сервер бота. Подробнее о Mini App — в статье Что такое Telegram Mini App.

Например, в проекте Wallner магазин для покупателей работает внутри Telegram Mini App, а оплата принимается через Click и Payme — там продаются физические товары. В боте VirtualPrinter для печати документов с доставкой тоже используется Click. Про подключение Click и Payme — в этой статье.

Telegram Stars в сумы: как это считается

Со стороны пользователя

Официального курса Stars к суму нет. По условиям Telegram пользователь покупает Stars через встроенные покупки в приложениях для iOS и Android, через PremiumBot или в веб- и десктоп-версиях Telegram. Цена зависит от платформы, комиссии магазина и способа оплаты. Поэтому, назначая цену в Stars, учитывайте, с каких устройств заходит ваша аудитория.

Со стороны владельца бота

Согласно условиям Telegram для разработчиков, полученные Stars можно потратить на рекламу или конвертировать в вознаграждение, а вознаграждения выплачиваются через платформу Fragment. На момент написания статьи в условиях были указаны вознаграждение 0,013 доллара США за одну Star и период ожидания до 21 дня после получения Stars. Там же сказано, что Fragment может не выплачивать вознаграждения в некоторых странах или некоторым пользователям.

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

Когда Stars, а когда Click или Payme

• Бот продаёт подписку или цифровой контент — Stars.
• Бот или Mini App продаёт физический товар — Click, Payme или другой провайдер.
• Есть и то, и другое — два платёжных потока: цифровая часть за Stars, физическая через обычного провайдера.

Стоимость бота зависит от функций — подробно в статье Сколько стоит Telegram-бот.

Чек-лист перед запуском

• Проверьте цену: сколько ваша цена в Stars реально стоит пользователю на iOS, Android и десктопе.
• Протестируйте выдачу товара: подписка, контент или функция открываются только после подтверждения оплаты.
• Защита от повторных оплат: если один счёт можно оплатить несколько раз, убедитесь, что вы корректно выполните каждый заказ.
• Опишите процесс возврата: в каких случаях возвращаются Stars и кто принимает решение.
• Добавьте команды поддержки: paysupport, условия использования и канал поддержки.
• Настройте отчётность: сколько Stars поступило и возвращено за день и какие товары продались — всё это должно быть видно в админке.

Если пройти этот список заранее, проблем с первыми пользователями будет гораздо меньше.

Подключение Stars в SyncLab

Мы подключаем оплату Stars в Telegram-ботах и Mini App: создание счетов, предварительная проверка, запись платежей в базу, возвраты и paysupport. Для физических товаров подключаем Click и Payme. На разработку Telegram-бота или подключение оплаты к существующему боту после короткого брифа присылаем письменное предложение с объёмом работ, сроками и фиксированной стоимостью. Если нужна сложная система, посмотрите направление разработка ПО на заказ.

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