Telegram Stars

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

Цены в базе хранятся в рублях — при оплате Stars они пересчитываются по курсу из настроек с округлением вверх, минимум 1 ★.

Что понадобится

Ничего. Ни регистрации у провайдера, ни ключей — инвойсы шлёт ваш же бот через Bot API. Достаточно рабочего бота.

Настройка в кабинете

У шлюза нет полей с кредами — карточка «Telegram Stars» в разделе провайдеров включается одним переключателем активности (is_active). Кнопка «Тест» всегда отвечает успехом: внешнего API у шлюза нет, проверять нечего.

Единственная настройка — курс пересчёта, и живёт она в общих настройках бота (категория «Платежи», см. /payments/settings):

Параметр	Что это	Дефолт
STARS_RATE_RUB	Курс Stars: сколько копеек стоит 1 ★. Количество звёзд в инвойсе = цена в копейках / курс, округление вверх	130

Вебхук

Вебхука нет — и настраивать его негде. У шлюза needs_http_webhook = false, а HTTP-маршрут /api/v1/payments/telegram_stars отвергает любой запрос с ошибкой верификации.

Подтверждение платежа идёт целиком внутри Telegram:

1. Бот отправляет инвойс с валютой XTR; в payload инвойса зашит внутренний payment_id транзакции.
2. Telegram присылает pre_checkout_query — бот подтверждает её.
3. После списания звёзд приходит апдейт successful_payment — бот достаёт payment_id из payload и проводит платёж через стандартный идемпотентный пайплайн (тот же, что у вебхуков).

Отсюда важное отличие от касс: платежи Stars подтверждает бот, а не веб-сервис. Если бот не получает апдейты — оплаты Stars не зачисляются.

Особенности

• Валюта только XTR, звёзды целые (без копеек). Округление всегда вверх — юзер не заплатит меньше цены.
• Пополнение внутреннего баланса тоже работает через Stars — это единственный in-bot способ пополнить кошелёк.
• При 100% скидке (free-path) инвойс не отправляется вовсе — подписка выдаётся сразу.
• Возвратов по API нет: refund у шлюза не реализован, возврат из кабинета фиксируется только записью (звёзды возвращаете вручную).
• Поллинга статуса нет: реконсилятор Stars-платежи не опрашивает — подтверждение приходит только апдейтом successful_payment. Если выдача упала после оплаты (например, панель была недоступна), юзер увидит «Оплата получена, но выдача задерживается».

Платёж прошёл, а выдача зависла?

Как устроен пайплайн подтверждения и добивание зависших платежей — см. /payments/webhooks.