Платежи и Telegram Stars

Монетизация — ключевой вопрос для любого приложения, и Telegram предоставляет два мощных механизма: TON-платежи для крипто-транзакций и Telegram Stars для покупок внутри приложения. Понимание обоих механизмов позволяет выбрать оптимальную стратегию монетизации для вашего продукта.

С 2024 года Telegram Stars (XTR) — обязательная виртуальная валюта для продажи цифровых товаров внутри Telegram. В этом уроке разберём архитектуру платёжного потока, отличие Stars от TON и паттерны интеграции.

Telegram Stars: концепция

Stars — это внутренняя валюта Telegram, обозначаемая XTR. Ключевые свойства:

Архитектура платёжного потока

Платёж через Stars — это 7-шаговый процесс между ботом, Telegram и пользователем:

Шаг 1: Создание инвойса (sendInvoice)

Бот отправляет инвойс с описанием товара:

// Pseudocode -- структура запроса sendInvoice
bot.sendInvoice({
  chat_id: userId,
  title: 'Премиум-подписка на 30 дней',
  description: 'Доступ к эксклюзивным материалам',
  payload: 'premium_30d_user123',    // ваш внутренний ID
  currency: 'XTR',                    // Stars
  prices: [{ label: 'Подписка', amount: 100 }],
});

Шаг 2-3: Инвойс и оплата

Telegram показывает нативный UI инвойса — вы не контролируете его внешний вид. Пользователь видит название, описание и сумму в Stars.

Шаг 4-5: Pre-checkout

Перед списанием Stars Telegram отправляет боту pre_checkout_query — последний шанс проверить заказ:

// Обработка pre_checkout_query
bot.on('pre_checkout_query', (query) => {
  const { id, invoice_payload, total_amount } = query;

  // Проверка: товар существует? цена корректна?
  const isValid = validateOrder(invoice_payload, total_amount);

  bot.answerPreCheckoutQuery(id, isValid, {
    error_message: isValid ? undefined : 'Товар больше не доступен',
  });
});

Шаг 6-7: Успешный платёж и доставка

// Обработка successful_payment
bot.on('message', (msg) => {
  if (msg.successful_payment) {
    const {
      telegram_payment_charge_id,  // ID транзакции Telegram
      invoice_payload,              // ваш payload из sendInvoice
      total_amount,                 // сумма в Stars
    } = msg.successful_payment;

    // Доставить цифровой товар
    deliverProduct(msg.from.id, invoice_payload);
  }
});

Stars vs TON: две валюты, два сценария

Важно понимать разницу между Stars и TON в контексте Mini App:

Типичный паттерн Mini App:

• Stars — для покупки внутренних товаров (подписки, контент, стикеры)
• TON — для blockchain-операций (минтинг NFT, swap токенов, staking)

Эти два метода оплаты не конкурируют — они решают разные задачи. Mini App может использовать оба одновременно.

Возврат средств

Stars поддерживают возврат в течение определённого окна:

// Получение транзакций
const transactions = await bot.getStarTransactions({
  offset: 0,
  limit: 100,
});

// Возврат средств
await bot.refundStarPayment(
  userId,
  telegramPaymentChargeId
);

Star Subscriptions: подписочная модель

С Bot API 8.0 (конец 2024) Telegram добавил подписки за Stars — регулярные списания с баланса пользователя по фиксированному периоду. Это даёт ботам и Mini App нативный recurring billing без необходимости поднимать собственную систему рекуррентных платежей.

Параметры подписки

Ключевое поле инвойса для подписки — subscription_period:

// createInvoiceLink с подпиской
const link = await bot.createInvoiceLink({
  title: 'Premium ежемесячно',
  description: 'Доступ к закрытым каналам и фичам',
  payload: 'sub_premium_user123',
  currency: 'XTR',
  prices: [{ label: 'Месяц', amount: 350 }],
  subscription_period: 2592000,   // 30 дней в секундах
});

После первой оплаты Telegram автоматически списывает указанную сумму каждые 30 дней и отправляет боту обновление о продлении.

Recurring billing flow

Шаг 1 (день 0):
  Бот -> createInvoiceLink(subscription_period=2592000)
  Пользователь оплачивает первый период.
  Бот получает successful_payment с subscription_expiration_date.

Шаг 2 (день 30):
  Telegram автоматически списывает 350 XTR.
  Бот получает обновление о продлении -- доступ продлевается.

Шаг 3 (отмена):
  Пользователь нажимает "Отменить" в меню Telegram.
  Бот получает обновление is_canceled=true.
  После окончания текущего периода доступ отзывается.

Сервер бота должен хранить subscription_expiration_date и is_canceled для каждого пользователя и проверять их при каждом запросе доступа — Telegram не присылает явного событие “доступ закончился”, это вычисляется сравнением дат.

PaidMedia: платный контент через Stars

Paid Media — механика, при которой бот публикует фото или видео, видимое только после оплаты Stars. Это не подписка, а разовая покупка конкретного поста, типичный кейс — gated-контент в каналах, генерация изображений по запросу, платные ответы AI-ассистента.

Отправка платного медиа

// Отправить платное фото в канал или личный чат
await bot.sendPaidMedia({
  chat_id: channelId,
  star_count: 50,                    // цена в Stars
  media: [{
    type: 'photo',
    media: 'https://cdn.example.com/exclusive.jpg',
  }],
  caption: 'Эксклюзивное фото из закрытого архива',
});

Подписчики видят размытое превью с кнопкой “Разблокировать за 50 XTR”; после оплаты медиа становится видимым только этому пользователю. Ни сервер бота, ни TON Connect не нужны — весь поток происходит внутри Telegram, бот получает событие об успешной оплате через стандартный successful_payment с полем paid_media.

Pre-checkout для PaidMedia

pre_checkout_query для PaidMedia работает как и для обычных Stars-инвойсов: у бота есть 10 секунд, чтобы подтвердить или отклонить покупку. Типичная валидация — проверить, что медиа всё ещё доступно (например, не было удалено модерацией) и цена не изменилась с момента публикации.

bot.on('pre_checkout_query', (query) => {
  if (query.invoice_payload.startsWith('paid_media:')) {
    const mediaId = query.invoice_payload.split(':')[1];
    const ok = paidMediaStore.exists(mediaId);
    bot.answerPreCheckoutQuery(query.id, ok, {
      error_message: ok ? undefined : 'Контент удалён',
    });
  }
});

Типичные применения

• Платные посты в каналах (фото/видео из эксклюзивного контента).
• AI-сервисы: image generation, video upscale, voice clone — бот возвращает результат как PaidMedia, оплата идёт за конкретный результат.
• Pay-per-view трансляции и записи событий.

Паттерн Stars в Mini App

В Mini App платёж обычно инициируется через бэкенд:

WebApp.openInvoice(url, callback) открывает нативный UI оплаты прямо внутри Mini App и возвращает результат в колбэк.

Итоги

В следующем уроке разберём TON Connect внутри Mini App — как интегрировать блокчейн-кошелёк с Telegram-платформой.

Частые ошибки

1. Путают TON-платежи и Telegram Stars: TON требует кошелёк и работает через блокчейн, Stars покупаются за фиат через App Store/Google Play.
2. Не обрабатывают webhook подтверждения для Stars-платежей: без серверной верификации злоумышленник может получить товар без оплаты.
3. Забывают о комиссии платформы: Apple и Google берут до 30% от Stars-платежей, и это нужно учитывать в ценообразовании.
4. Не предусматривают механизм возврата (refund): пользователи имеют право на возврат средств, и ваш бэкенд должен это поддерживать.