Telegram Stars для ботов — как принимать платежи во внутренней валюте Telegram

Telegram Stars (код валюты XTR) — виртуальная расчётная единица Telegram для покупки цифровых товаров и услуг в ботах и мини-приложениях (Mini Apps). Она позволяет принимать платежи внутри Telegram без подключения внешнего платёжного провайдера.

Материал основан на документации и не заявляет о самостоятельном тестировании описанных сценариев.

Содержание

1. Что такое Telegram Stars и где они обязательны
2. Возможности для ботов и каналов
3. Экономика, баланс и вывод
4. Разовые платежи через Bot API
5. Подписки на Stars
6. Gifts и другие операции
7. Лимиты и ограничения
8. Полезные сценарии
9. Проверка результата и чек-лист запуска
10. Официальные ссылки

Что такое Telegram Stars и где они обязательны

Пользователь приобретает Stars через доступные в его клиенте способы, включая покупки через Apple и Google, @PremiumBot и Fragment, а затем расходует их внутри Telegram.

Для продажи цифровых товаров и услуг внутри приложений Telegram бот или Mini App должен использовать Stars. Это относится к подпискам, доступу к контенту, генерациям в AI-боте и виртуальным предметам. Обойти это требование с помощью внешнего сайта или стороннего платёжного провайдера для продажи внутри Telegram нельзя.

Для физических товаров и услуг применяются обычные платежи Bot Payments API с поддерживаемыми валютами и провайдерами.

Возможности для ботов и каналов

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

Экономика, баланс и вывод

Цена покупки Stars зависит от выбранного способа оплаты и применимых налогов и сборов. Официальная документация предупреждает, что итоговые суммы могут различаться у пользователей. Поэтому фиксированный курс вроде «1 Star = определённая сумма в долларах» нельзя использовать в финансовой модели без актуальной проверки.

После успешного платежа Stars поступают на баланс бота. Историю операций можно получить через getStarTransactions, а текущий баланс — через getMyStarBalance. На уровне Telegram API доступны также статистика выручки, доступный для вывода баланс и текущий курс конвертации Stars в USD.

Заработанные Stars можно:

1. Конвертировать в вознаграждение с выводом через Fragment на TON-кошелёк, если вывод доступен владельцу и выполнены текущие требования Telegram.
2. Направить на Telegram Ads для принадлежащего владельцу бота или канала. Официальная документация указывает скидку 30% для такой оплаты.
3. Использовать для поддерживаемых внутренних операций, например для возвратов. Операции с подарками и переводами зависят от типа аккаунта и конкретного объекта.

Разовые платежи через Bot API

Минимальный рабочий поток состоит из четырёх этапов:

1. Отправить инвойс с currency: "XTR".
2. Получить pre_checkout_query и ответить на него в течение 10 секунд.
3. Дождаться successful_payment.
4. Сохранить telegram_payment_charge_id и только после этого выдать товар.

Python: создание инвойса

from telegram import LabeledPrice

async def buy(update, context):
    await context.bot.send_invoice(
        chat_id=update.effective_chat.id,
        title="Premium доступ",
        description="30 дней доступа к функциям AI-бота",
        payload="premium_30d",
        provider_token="",
        currency="XTR",
        prices=[LabeledPrice("Premium 30 дней", 500)],
    )

Node.js: создание инвойса

bot.command("buy", async (ctx) => {
  await ctx.telegram.sendInvoice(ctx.chat.id, {
    title: "Premium доступ",
    description: "30 дней доступа к функциям AI-бота",
    payload: "premium_30d",
    provider_token: "",
    currency: "XTR",
    prices: [{ label: "Premium", amount: 500 }]
  });
});

Сигнатуры SDK могут отличаться между версиями. Перед внедрением проверьте документацию используемой библиотеки и соответствие её версии текущему Bot API.

Подтверждение оплаты

async def pre_checkout(update, context):
    query = update.pre_checkout_query

    # Здесь проверьте payload, цену и возможность выдать товар.
    await query.answer(ok=True)

async def on_paid(update, context):
    payment = update.message.successful_payment

    save_purchase(
        user_id=update.effective_user.id,
        charge_id=payment.telegram_payment_charge_id,
        stars=payment.total_amount,
        payload=payment.invoice_payload,
    )

    # Выдавайте товар идемпотентно после фиксации платежа.

Ответ на pre_checkout_query подтверждает готовность принять заказ, но не доказывает успешную оплату. Выдавайте товар только после successful_payment.

Для пересылаемых инвойсов, счетов во встроенном inline-режиме и многоразовых инвойсов отдельно контролируйте допустимость повторной покупки. Проверяйте payload, сумму, пользователя и уже обработанный telegram_payment_charge_id.

Возврат платежа

await bot.refund_star_payment(
    user_id=user_id,
    telegram_payment_charge_id=charge_id,
)

Возврат списывает соответствующие Stars с баланса бота и возвращает их пользователю. Бот обязан отвечать на /paysupport и самостоятельно обрабатывать платежные споры. Telegram также рекомендует предоставить понятные условия через /terms или другой доступный способ.

Подписки на Stars

Ссылку на подписку можно создать через createInvoiceLink, передав subscription_period. Поддерживаемый период для Stars-подписки — 30 дней, то есть 2592000 секунд.

link = await bot.create_invoice_link(
    title="Premium",
    description="Ежемесячный доступ",
    payload="premium_sub",
    provider_token="",
    currency="XTR",
    prices=[LabeledPrice("Premium / месяц", 350)],
    subscription_period=2592000,
)

После оплаты Telegram выполняет периодические списания при наличии средств. Продления отражаются в платежных обновлениях. Начиная с Bot API 10.2, изменения пользовательской подписки также могут приходить в обновлении subscription как объект BotSubscriptionUpdated.

В приложении храните собственное состояние доступа и обрабатывайте повторные события идемпотентно. Не рассчитывайте срок доступа только от момента создания ссылки.

Gifts и другие операции

Метод sendGift позволяет боту отправить доступный подарок пользователю или каналу. Перед отправкой сверяйте в актуальном Bot API доступность подарка, его цену и ограничения: ассортимент, доступность и тираж могут меняться.

Для подключённого бизнес-аккаунта Bot API предоставляет отдельные операции:

• getBusinessAccountGifts — получить подарки аккаунта;
• convertGiftToStars — конвертировать поддерживаемый подарок в Stars;
• upgradeGift — улучшить обычный подарок до уникального;
• transferGift — передать уникальный подарок;
• getBusinessAccountStarBalance и transferBusinessAccountStars — работать с балансом бизнес-аккаунта в разрешённых пределах.

Обычные и уникальные подарки имеют разные свойства и ограничения. Не обещайте пользователю возможность обратной конвертации или передачи конкретного подарка, пока API не подтвердил её для этого объекта.

Лимиты и ограничения

Для обычного разового инвойса не переносите лимиты подписок или paid media автоматически. Проверяйте актуальные ограничения конкретного метода в Bot API.

Stars могут быть недоступны отдельным пользователям из-за региональных ограничений. Клиенты Telegram получают для этого признак stars_purchase_blocked; продукту нужен понятный сценарий отказа, если покупка недоступна.

Когда Stars не подходят

• Вы продаёте физические товары или услуги: используйте обычные платежные провайдеры Bot Payments API.
• Вам нужен B2B-документооборот со счётом, актом, НДС или другими документами: одной интеграции Stars для этого недостаточно, требования к оформлению нужно проверить отдельно.
• Финансовая модель чувствительна к точному курсу и сроку вывода: цена покупки, расчетное вознаграждение и доступность вывода меняются.
• Требуется способ оплаты, недоступный внутри Telegram или запрещённый правилами магазинов приложений.

Полезные сценарии

Продажа пакета генераций в AI-боте

Задача: брать оплату за ресурсоёмкие запросы без отдельной платёжной формы.

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

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

Доступ по подписке

Задача: предоставлять премиум-функции на оплаченный период.

Бот создаёт ссылку с subscription_period=2592000, принимает платежные обновления и хранит дату окончания доступа. Проверяемый результат — активный статус подписки в базе приложения и доступ к закрытой функции.

Ограничение: нужно обрабатывать нехватку Stars, повторные уведомления и изменение состояния подписки.

Разовая продажа цифрового материала

Задача: выдать файл, ссылку или доступ после оплаты.

После подтверждённого платежа бот записывает заказ и отправляет материал. Повторная доставка с тем же telegram_payment_charge_id не должна создавать второй заказ.

Ограничение: продавец отвечает за поддержку, условия продажи и споры. Для физической доставки этот поток не подходит.

Монетизация канала

Задача: получать Stars за контент и поддержку аудитории.

Канал может использовать платные реакции, подписочные приглашения, paid media или giveaways. Результат проверяется по балансу, истории транзакций и состоянию соответствующей публикации или подписки.

Ограничение: интерфейсы каналов и Bot API решают разные задачи; наличие функции в канале не означает, что у неё есть одноимённый метод для обычного бота.

Проверка результата и чек-лист запуска

Минимальная проверка платежного контура:

1. Подключите бота к тестовому окружению Telegram.
2. Создайте инвойс в XTR на небольшое целое количество тестовых Stars.
3. Убедитесь, что бот получает pre_checkout_query и отвечает быстрее 10 секунд.
4. Завершите оплату и проверьте получение successful_payment.
5. Сверьте invoice_payload, total_amount и telegram_payment_charge_id с сохранённым заказом.
6. Повторно передайте то же событие обработчику: товар не должен выдаваться второй раз.
7. Выполните тестовый возврат и проверьте изменение состояния заказа и баланса.

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

Официальные ссылки

• Bot Payments API for Digital Goods and Services
• Справочник Telegram Bot API
• Changelog Telegram Bot API
• Telegram Stars API
• Star Reactions and Subscriptions
• Вывод Stars и 21-дневное окно

Следующий шаг

Telegram Business Bots — как боты управляют бизнес-аккаунтом в Telegram

Связанные материалы

• Статья: Делай, брат, делай! Два месяца pimenov.ai и что я понял про ИИ-агентов
• Блог: Люди + агенты в одном чате: как мы собрали рабочий контур в Telegram
• База знаний: Возможности Telegram-ботов — справочник по Bot Features

Если вы проектируете монетизацию бота или Mini App, полезно заранее проверить платежный поток, возвраты и экономику вывода на вашей модели доступа.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov