Оплата звёздами Telegram
Как принимать оплату Telegram Stars в Mini App, какой курс звезды выбрать и как вывести заработанные звёзды через Fragment.
Telegram Stars — внутренняя валюта Telegram. Клиент покупает звёзды в самом Telegram и платит ими за пакет прямо в Mini App вашего бота. Договоров, ключей и вебхуков не нужно: оплату принимает ваш бот.
Что где лежит в админке, описано в справочнике Настройки → Платежи.
Что понадобится
- Бот сервиса, подключённый к Reefox Panel и запущенный. Как его создать — на странице Бот в BotFather.
- Доступ к Telegram-аккаунту, который владеет ботом. Только с него видно баланс звёзд и можно их вывести.
- Двухэтапная проверка (облачный пароль) на этом аккаунте. Без неё Telegram не даст вывести звёзды.
- Для вывода — TON-кошелёк.
Статус ИП, ООО или самозанятого для приёма звёзд не нужен. Как учитывать такой доход, обсудите с бухгалтером.
Шаг 1. Включите Stars
В админке Reefox Panel откройте Настройки → Платежи → Подключения и раскройте Telegram Stars.
Задайте «Стоимость одной звезды, ₽». По умолчанию 2.5. Как выбрать курс — ниже.
Включите переключатель «Включить Telegram Stars» и нажмите «Сохранить платежи».
Под полем видно правило, например «1 Star = 2.5 ₽». Клиенты в Mini App увидят способ Telegram Stars.
Шаг 2. Выберите курс звезды
Курс — сколько рублей стоит одна звезда в ваших ценах. Цена пакета делится на курс и округляется до целой звезды.
| Цена пакета | Курс | Клиент платит |
|---|---|---|
| 299 ₽ | 2.5 | 120 звёзд |
| 299 ₽ | 1.5 | 199 звёзд |
| 2 990 ₽ | 2.5 | 1 196 звёзд |
Чем меньше курс, тем больше звёзд платит клиент и тем больше получаете вы.
По правилам Telegram для разработчиков одна звезда при выводе стоит 0,013 $. Чтобы получать со звёзд примерно столько же, сколько с оплаты по СБП, курс в админке должен быть около 0,013 × курс доллара в рублях. Учтите, что звёзды выводятся в Toncoin, и итог в рублях зависит ещё и от курса TON.
Клиент сам покупает звёзды в Telegram, и для него они дороже 0,013 $. Поэтому низкий курс делает оплату звёздами заметно дороже СБП. Курс — ваше решение: выше — дешевле для клиента, ниже — выгоднее вам.
Шаг 3. Проверочная оплата
Откройте Mini App вашего бота со своего аккаунта. На сайте способа Stars нет — только в Mini App.
Купите самый дешёвый пакет, способ — Telegram Stars. Если звёзд нет, Telegram предложит их купить.
Подтвердите оплату. Проверьте, что доступ продлился, а в разделе Платежи оплата стала «Оплачен».
Откройте баланс бота — см. шаг 4. Звёзды появятся там, а вывести их можно будет позже.
Шаг 4. Как вывести звёзды
С аккаунта-владельца откройте профиль бота в Telegram, нажмите «Изменить» и выберите «Баланс».
Нажмите вывод. Telegram попросит облачный пароль двухэтапной проверки.
Откроется страница Fragment. Укажите адрес TON-кошелька и подтвердите вывод. Звёзды придут в Toncoin.
- До 21 дня. Полученные звёзды становятся доступны для вывода или рекламы не сразу, а в течение 21 дня.
- Минимум и максимум. Минимальную и максимальную сумму вывода задаёт Telegram. Вы увидите их при выводе.
- Срок жизни. Заработанные звёзды действуют 3 года с даты получения.
- Страны. Fragment может не обработать вывод в некоторых странах из-за местных правил.
- Реклама. Звёзды можно не выводить, а потратить на рекламу бота в Telegram Ads — со скидкой 30 %.
Ограничения
- Stars работают только в Mini App. На сайте клиент видит СБП, карту и другие способы.
- Автопродления через звёзды нет. Для автопродления нужны ЮKassa или Platega.
- Минимальная сумма — одна звезда. Минимальная цена в рублях равна курсу, округлённому до целого.
- Бот должен работать. Telegram ждёт от бота ответ перед оплатой не дольше 10 секунд. Если бот выключен или сервер лежит, оплата не пройдёт, а звёзды не спишутся.
- Если счёт истёк — прошло 15 минут, — бот откажет в оплате: «Срок счёта истёк. Создай новый в кабинете.» Клиенту нужно открыть оплату заново.
- Если включены чеки «Мой Налог», чек по оплате звёздами создаётся на цену пакета в рублях. По умолчанию тумблер для Stars включён. Согласуйте с бухгалтером, нужен ли он вам.
Правило Telegram о цифровых товарах
Telegram требует, чтобы цифровые товары и услуги внутри приложений Telegram продавались только за звёзды. Иначе, по словам Telegram, он может не показывать бота или Mini App пользователям мобильных приложений. Reefox Panel показывает в Mini App и другие способы оплаты. Оцените этот риск сами.
Возвраты и споры
По правилам Telegram за споры по оплате отвечает владелец бота. Бот должен отвечать на команду /paysupport и разбирать обращения по платежам.
- Кнопки возврата звёзд в Reefox Panel нет. Telegram возвращает звёзды только по запросу бота через API.
- Отдельной команды
/paysupportв боте Reefox Panel нет. Укажите в описании бота, куда писать по вопросам оплаты, и отвечайте через поддержку.
Частые ошибки
| Что видно | Причина | Что сделать |
|---|---|---|
| Способа Stars нет у клиента | Клиент на сайте, а не в Mini App, или Stars выключены | Откройте Mini App. Проверьте переключатель и курс |
| «Произошла ошибка при обработке платежа. Попробуйте позже.» | Сервер не смог проверить счёт | Проверьте, что Reefox Panel работает, и попробуйте снова |
| «Срок счёта истёк. Создай новый в кабинете.» | Прошло больше 15 минут | Клиенту открыть оплату заново |
| «Счёт недоступен. Открой оплату в кабинете.» | Счёт уже оплачен, заменён или открыт с другого аккаунта | Клиенту открыть оплату заново со своего аккаунта |
| Звёзды есть, а вывести нельзя | Не прошло 21 дня, баланс меньше минимума или нет двухэтапной проверки | Подождите или включите облачный пароль |
| Баланс звёзд не виден | Вы зашли не с аккаунта-владельца бота | Войдите в аккаунт, который создал бота в BotFather |