Гайд · Telegram Stars

Счёт в Telegram Stars (XTR) в боте: платёжный поток для разработчиков по шагам

Как продавать цифровой товар за Stars через бота: sendInvoice с валютой XTR, ответ на pre_checkout_query за 10 секунд, successful_payment, хранение charge_id, режимы пересылки и чек-лист запуска.

Опубликовано:

Счёт в Telegram Stars (XTR) в боте: платёжный поток для разработчиков по шагам

Ваш бот продаёт цифровое — подписку, контент, AI-запросы или игровые предметы? Тогда оплата только в Telegram Stars. Эта статья по шагам показывает поток счёта в Telegram Stars (XTR) глазами разработчика, по официальной документации Bot API. Почему именно Stars: цифровые товары в ботах только за Stars.

Поток с высоты

ШагЧто делает ботЧто присылает Telegram
1sendInvoice, currency = XTR—
2Ждётpre_checkout_query
3answerPreCheckoutQuery (за 10 секунд)—
4Ждётsuccessful_payment
5Сохраняет charge_id, выдаёт товар—

Шаг 1. Создать счёт

Два пути:

  • Счёт от бота — метод sendInvoice. Товар цифровой, поэтому provider_token — пустая строка, а в поле валюты — XTR. Счёт можно отправить в личный чат, группу или канал.
  • Inline-счёт — если бот поддерживает inline-режим, через inputInvoiceMessageContent пользователи делятся счётом с друзьями, в группах и каналах. Кнопка Pay у такого счёта многоразовая.

Шаг 2. Выбрать поведение при пересылке

Управляется параметром start_parameter:

  1. Мультичатовый счёт — у пересланных копий тоже есть кнопка Pay, платить могут многие. Inline-счета всегда такие.
  2. Одночатовый счёт — оплачивается только в чате, куда отправлен; у копий вместо Pay — кнопка с deep link на бота.

Важно: одночатовый счёт в личном чате с ботом оплачивается только один раз. В любом случае решать, принимать ли новый платёж, — боту.

Шаг 3. Pre-checkout

Пользователь (при необходимости докупив Stars) нажимает Pay. Бот получает pre_checkout_query с данными заказа и должен ответить answerPreCheckoutQuery в течение 10 секунд — иначе транзакция отменится. Если отказываете, объясните причину человеческим языком: Telegram покажет её пользователю.

Шаги 4–5. Оплата и выдача

При успешной оплате приходит successful_payment. Только после этого выдавайте товар — ответ на pre_checkout_query ещё не гарантирует оплату. Сохраните telegram_payment_charge_id: он нужен для возврата.

Перед запуском

  • Включите двухэтапную проверку на аккаунте владельца бота.
  • Условия по команде /terms, поддержка по /support и /paysupport.
  • Будьте готовы к спорам и возвратам — refundStarPayment. Подробнее: возврат Stars и /paysupport.
  • Стабильный сервер и резервные копии данных о платежах.

Как тестировать

В отдельной тестовой среде Telegram платежи в Stars тестируются бесплатно. Когда всё работает — переключаетесь на продакшн.

Сторона покупки Stars

Пользователи покупают Stars в приложении или через @PremiumBot, а PayStars продаёт их за USDT. Если вашему сервису нужно покупать Stars автоматически, помогут API PayStars и обзор API.

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

Можно принимать крипту или другую валюту вместо Stars?

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

Как протестировать оплату?

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

Как сделать возврат?

Методом refundStarPayment в Bot API.

Источники

Покупайте Stars и Premium за USD (USDT)

Через API-ключ: 0% (цена Fragment). Через сайт: 5%.

Начать