Платежи и 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
);

Паттерн 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): пользователи имеют право на возврат средств, и ваш бэкенд должен это поддерживать.