Оплата Telegram Stars в боте: счета, pre-checkout, возвраты и подписки
Чтобы принимать оплату в Telegram Stars в боте, отправьте счёт методом sendInvoice с валютой XTR и пустым provider_token, ответьте на апдейт pre_checkout_query методом answerPreCheckoutQuery в течение 10 секунд и выдавайте товар только после сообщения с successful_payment. Telegram Stars — обязательная валюта для цифровых товаров и услуг, которые продаются в приложениях Telegram. Ниже — весь процесс с рабочим ботом на Python и JavaScript, а также возвраты, история транзакций, подписки и платный контент.
Как работает оплата Telegram Stars в боте
Telegram Stars — внутренняя виртуальная валюта. Пользователи покупают звёзды через встроенные покупки Apple и Google или через @PremiumBot и тратят их в вашем боте; персональные данные форма оплаты не запрашивает. Схема такая:
- Бот отправляет счёт:
sendInvoiceв чат илиcreateInvoiceLinkдля ссылки. - Пользователь нажимает Pay (при необходимости сначала докупает звёзды).
- Бот получает апдейт с
pre_checkout_query. - Бот подтверждает или отклоняет заказ через
answerPreCheckoutQuery— не позже чем через 10 секунд. - Telegram присылает служебное сообщение с
successful_payment. - Бот сохраняет
telegram_payment_charge_idи выдаёт товар.
Цифровые товары продаются только за звёзды. Telegram прямо указывает: бот или Mini App должны использовать Telegram Stars для продажи цифровых товаров и услуг внутри приложений Telegram, независимо от вашего сайта или платёжных провайдеров вне Telegram; иначе Telegram не сможет показывать бота пользователям мобильных приложений. Другие валюты и провайдеры допустимы только для физических товаров — там отдельная схема с provider token.
Отправка счёта: sendInvoice и XTR
Минимальный счёт на 50 звёзд:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendInvoice" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"title": "Pro-пакет",
"description": "50 дополнительных генераций изображений",
"payload": "pro-pack-v1",
"provider_token": "",
"currency": "XTR",
"prices": [{"label": "Pro-пакет", "amount": 50}]
}'
Метод возвращает отправленное сообщение (Message). Параметры, важные для Stars:
| Параметр | Правило для Telegram Stars |
|---|---|
title | Название товара, 1–32 символа. |
description | Описание товара, 1–255 символов. |
payload | 1–128 байт, пользователю не показывается. Храните здесь id заказа или товара: он вернётся в pre-checkout запросе и в платеже. |
provider_token | Необязательный; для Stars — пустая строка. |
currency | XTR. |
prices | Массив LabeledPrice, в котором должен быть ровно один элемент; amount — цена в звёздах (целое число). |
start_parameter | Пустой — у пересланных копий остаётся кнопка оплаты. Непустой — вместо неё пересланные копии показывают URL-кнопку с deep link на бота. |
photo_url | Необязательная картинка товара, вместе с photo_size, photo_width, photo_height. |
Чаевые (max_tip_amount) в Stars не поддерживаются, а need_name, need_email, need_shipping_address, is_flexible и похожие поля игнорируются. Если задаёте свою reply_markup, первой должна идти кнопка оплаты ("pay": true); подстроки ⭐ и XTR в её тексте заменяются иконкой звезды. Счёт можно отправить в личный чат, группу или канал. Попробовать без кода: откройте sendInvoice в Bot API Tester, заполните поля из таблицы и отправьте счёт себе.
createInvoiceLink для Mini Apps и сайтов
createInvoiceLink принимает те же title, description, payload, currency и prices, но вместо отправки сообщения возвращает ссылку на счёт строкой. Откройте её в Mini App через Telegram.WebApp.openInvoice(url) или поделитесь как обычной ссылкой. Этот же метод используется для подписок (см. ниже).
Ответ на pre_checkout_query за 10 секунд
Когда пользователь нажимает Pay, бот получает PreCheckoutQuery с полями id, from, currency, total_amount и invoice_payload. Ответить нужно в течение 10 секунд, иначе транзакция отменится:
ok: true— товар есть и вы готовы выполнить заказ.ok: falseиerror_message— понятная причина, которую Telegram покажет пользователю, например «Предложение устарело, отправьте /buy, чтобы получить новый счёт».
Обработчик должен быть быстрым: проверили payload и наличие, ответили, остальное — потом. Подтверждение запроса не означает, что деньги пришли.
Выдача товара после successful_payment
Успешный платёж приходит как message с полем successful_payment, где есть currency, total_amount, invoice_payload и telegram_payment_charge_id. Правило Telegram однозначно: перед выдачей товара всегда убедитесь, что получили successful_payment. Сохраните telegram_payment_charge_id вместе с id покупателя — для возврата нужны оба.
Полный пример: бот, который продаёт за Telegram Stars
Этот бот на long polling отправляет счёт по команде /buy, проверяет pre-checkout запрос, записывает платёж и отвечает на /paysupport. Обратите внимание на allowed_updates: если вы ограничиваете типы апдейтов, добавьте pre_checkout_query, иначе платежи до бота не дойдут.
import json
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
PAYLOAD = "pro-pack-v1"
PRICE = 50 # в Telegram Stars
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
def handle(update):
query = update.get("pre_checkout_query")
if query:
ok = (query["invoice_payload"] == PAYLOAD and query["currency"] == "XTR"
and query["total_amount"] == PRICE)
answer = {"pre_checkout_query_id": query["id"], "ok": ok}
if not ok:
answer["error_message"] = "Предложение устарело. Отправьте /buy, чтобы получить новый счёт."
call("answerPreCheckoutQuery", **answer) # не позже чем через 10 секунд
return
msg = update.get("message")
if not msg:
return
chat_id = msg["chat"]["id"]
if "successful_payment" in msg:
payment = msg["successful_payment"]
with open("payments.jsonl", "a") as f: # charge id нужен для возвратов
f.write(json.dumps({"user_id": msg["from"]["id"],
"charge_id": payment["telegram_payment_charge_id"],
"payload": payment["invoice_payload"],
"amount": payment["total_amount"]}) + "\n")
call("sendMessage", chat_id=chat_id, text="Спасибо! Pro-пакет активирован.")
elif msg.get("text") == "/buy":
call("sendInvoice", chat_id=chat_id, title="Pro-пакет",
description="50 дополнительных генераций изображений",
payload=PAYLOAD, provider_token="", currency="XTR",
prices=[{"label": "Pro-пакет", "amount": PRICE}])
elif msg.get("text") == "/paysupport":
call("sendMessage", chat_id=chat_id,
text="Проблема с оплатой? Опишите её одним сообщением, мы ответим в течение 24 часов.")
offset = 0
while True:
updates = call("getUpdates", offset=offset, timeout=30,
allowed_updates=["message", "pre_checkout_query"])
for update in updates:
offset = update["update_id"] + 1
handle(update)import { appendFile } from "node:fs/promises";
const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const PAYLOAD = "pro-pack-v1";
const PRICE = 50; // в Telegram Stars
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
async function handle(update) {
const query = update.pre_checkout_query;
if (query) {
const ok = query.invoice_payload === PAYLOAD && query.currency === "XTR"
&& query.total_amount === PRICE;
const answer = { pre_checkout_query_id: query.id, ok };
if (!ok) answer.error_message = "Предложение устарело. Отправьте /buy, чтобы получить новый счёт.";
await call("answerPreCheckoutQuery", answer); // не позже чем через 10 секунд
return;
}
const msg = update.message;
if (!msg) return;
const chatId = msg.chat.id;
if (msg.successful_payment) {
const payment = msg.successful_payment;
await appendFile("payments.jsonl", JSON.stringify({ // charge id нужен для возвратов
user_id: msg.from.id,
charge_id: payment.telegram_payment_charge_id,
payload: payment.invoice_payload,
amount: payment.total_amount,
}) + "\n");
await call("sendMessage", { chat_id: chatId, text: "Спасибо! Pro-пакет активирован." });
} else if (msg.text === "/buy") {
await call("sendInvoice", {
chat_id: chatId, title: "Pro-пакет",
description: "50 дополнительных генераций изображений",
payload: PAYLOAD, provider_token: "", currency: "XTR",
prices: [{ label: "Pro-пакет", amount: PRICE }],
});
} else if (msg.text === "/paysupport") {
await call("sendMessage", {
chat_id: chatId,
text: "Проблема с оплатой? Опишите её одним сообщением, мы ответим в течение 24 часов.",
});
}
}
let offset = 0;
while (true) {
const updates = await call("getUpdates", {
offset, timeout: 30, allowed_updates: ["message", "pre_checkout_query"],
});
for (const update of updates) {
offset = update.update_id + 1;
await handle(update);
}
}Сохраните JavaScript-версию как bot.mjs (Node.js 18+). В продакшене используйте настоящую базу данных и делайте выдачу идемпотентной по telegram_payment_charge_id. С вебхуком обработчик тот же; настройка и allowed_updates — в гайде вебхук Telegram-бота.
Возврат платежа: refundStarPayment
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/refundStarPayment" \
-H "Content-Type: application/json" \
-d '{"user_id": 123456789, "telegram_payment_charge_id": "CHARGE_ID_FROM_SUCCESSFUL_PAYMENT"}'
При успехе метод возвращает true, звёзды возвращаются пользователю, а в чат приходит служебное сообщение с refunded_payment. Отзовите то, что успели выдать. Учтите: если покупатель оформит chargeback у Apple или Google, возвращённые звёзды спишутся с баланса бота — по словам Telegram, это вне его контроля.
Баланс и транзакции: getMyStarBalance, getStarTransactions
getMyStarBalanceвызывается без параметров и возвращает текущий баланс бота в видеStarAmount.getStarTransactionsвозвращаетStarTransactionsв хронологическом порядке; пагинация —offsetиlimit(1–100, по умолчанию 100). Для входящих платежей пользователейStarTransaction.idсовпадает сtelegram_payment_charge_id, аsourceописывает плательщика — удобно для сверки с вашими записями.
Подписки за Telegram Stars
Передайте subscription_period в createInvoiceLink, чтобы списывать оплату каждые 30 дней:
currency— толькоXTR, аsubscription_periodпока всегда должен быть2592000(30 дней).- Цена подписки не больше 10000 звёзд. Активных подписок у бота может быть сколько угодно, в том числе несколько от одного пользователя.
- Каждое списание приходит как
successful_payment:is_first_recurringотмечает первый платёж,is_recurring— продления, аsubscription_expiration_dateпоказывает, до какого момента доступ оплачен. editUserStarSubscriptionсuser_id,telegram_payment_charge_idиis_canceled: trueотключает продление (доступ сохраняется до конца оплаченного периода);is_canceled: falseснова включает подписку, отменённую ботом.
Для платного доступа в канал есть createChatSubscriptionInviteLink с subscription_period 2592000 и subscription_price от 1 до 10000 звёзд; боту нужно право администратора can_invite_users.
Платный контент коротко
sendPaidMedia отправляет до 10 фото или видео, скрытых за ценой: star_count 1–25000 и необязательный payload 0–128 байт. В канале выручка идёт на баланс канала, в остальных чатах — на баланс бота. Если payload непустой и чат не канал, бот получает апдейт purchased_paid_media с покупателем и payload — добавьте его в allowed_updates, если фильтруете апдейты.
Тестирование платежей в тестовом окружении
Telegram разрешает свободно тестировать платежи в Stars в отдельном тестовом окружении: создайте там тестовый аккаунт и бота и отправляйте запросы на https://api.telegram.org/bot<token>/test/METHOD_NAME. В нашем тестере для этого есть переключатель TEST. Пошаговая инструкция — в гайде тестовый сервер Telegram. Для запуска в бой переключите бота на рабочее окружение.
Чек-лист перед запуском и типичные проблемы
- Платёж отменяется после нажатия Pay: бот не ответил на
pre_checkout_queryза 10 секунд. Проверьте, что этот тип есть вallowed_updatesи что до ответа не выполняется долгая работа. - Счёт не отправляется: для Stars в
pricesдолжен быть ровно один элемент,currency—XTR, чаевые не поддерживаются. Читайтеdescriptionв ответе с ошибкой. - Товар выдан без оплаты: выдавайте его по
successful_payment, а не по pre-checkout запросу. - Один счёт оплатили несколько человек: пересланные счета и счета в группах можно оплатить многократно. Отклоняйте лишние платежи на этапе pre-checkout, если заказ нельзя выполнить дважды.
- Поддержка и условия: Telegram требует, чтобы бот отвечал на
/paysupport, и рекомендует команду/terms; поддержка Telegram не помогает с покупками, сделанными через ваш бот. - Аккаунт и данные: включите двухэтапную аутентификацию на аккаунте-владельце бота и делайте резервные копии данных о платежах.
Только начинаете? Прочитайте, как создать бота в Telegram. Официальная документация: платежи в Telegram Stars и раздел Payments в Bot API.
Частые вопросы
Как принимать оплату в Telegram Stars в боте?
Отправьте счёт методом sendInvoice (или createInvoiceLink) с currency XTR, пустым provider_token и ровно одним элементом в prices. На апдейт pre_checkout_query ответьте answerPreCheckoutQuery в течение 10 секунд, а товар выдавайте, когда придёт сообщение с successful_payment.
Нужен ли provider token для Telegram Stars?
Нет. provider_token нужен только для физических товаров и услуг. Для оплаты в Telegram Stars передайте пустую строку или не указывайте параметр.
Можно ли продавать цифровые товары в боте за рубли, доллары, карты или криптовалюту?
Нет. По правилам Telegram цифровые товары и услуги внутри приложений Telegram оплачиваются только в Telegram Stars — из-за требований App Store и Google Play. Другие валюты и платёжные провайдеры разрешены только для физических товаров и услуг.
Как вернуть оплату в Telegram Stars?
Вызовите refundStarPayment с user_id покупателя и telegram_payment_charge_id из сообщения successful_payment. Сохраняйте этот идентификатор для каждого платежа, иначе вернуть деньги позже не получится.
Как работают подписки за Telegram Stars в боте?
Создайте ссылку на счёт через createInvoiceLink с subscription_period = 2592000 (30 дней — пока единственное допустимое значение); цена не больше 10000 звёзд. Продления приходят как successful_payment с is_recurring, а editUserStarSubscription отменяет или снова включает продление.
Как бесплатно протестировать оплату в Telegram Stars?
Используйте тестовое окружение Telegram: создайте там тестовый аккаунт и бота и отправляйте запросы на /bot<token>/test/METHOD_NAME. По словам Telegram, платежи в Stars там можно тестировать свободно.
Читайте также
Как создать бота в Телеграм: от @BotFather до первого сообщения
Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.
Как задеплоить Telegram-бота: VPS, Docker и serverless-хостинг
Как задеплоить Telegram-бота: polling или вебхук, сервис systemd на VPS, Docker, Cloudflare Workers с secret_token и чек-лист перед запуском.
Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим
Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.
Ошибки Telegram Bot API: что означает каждая ошибка и как её исправить
Ошибки Telegram Bot API с решениями: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 и retry_after. Таблица причин и код обработки.
Лимиты Telegram Bot API: сообщения в секунду, ошибка 429 и размеры файлов
Все лимиты Telegram Bot API в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.
Команды Telegram-бота: setMyCommands, области видимости и deep link для /start
Настройка команд Telegram-бота: /setcommands в @BotFather, setMyCommands с областями и языками, параметр /start в deep link и команды /cmd@bot в группах.
Клавиатуры Telegram-бота: инлайн-кнопки, callback_data и reply-клавиатура
Кнопки Telegram-бота: инлайн-клавиатура с callback_data, answerCallbackQuery, редактирование сообщения после нажатия, reply-клавиатура и ForceReply.
Интеграция n8n и Telegram: подключение бота, Telegram Trigger и отправка сообщений
Как подключить Telegram к n8n: токен бота в Access Token, вебхук Telegram Trigger по публичному HTTPS, отправка сообщений по chat id и разбор ошибок.
Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки
Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.
Токен бота Telegram: как получить, где найти, как проверить и отозвать
Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.
Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление
Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.
Как узнать chat id в Telegram: пользователь, группа, канал и тема форума
Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.
Инлайн-бот Telegram: как включить inline mode и отвечать на инлайн-запросы
Как сделать инлайн-бота Telegram: включить inline mode через @BotFather или setMySettings, обработать inline_query и ответить через answerInlineQuery.
Тестовый сервер Telegram: как тестировать бота в тестовом окружении
Тестовый сервер Telegram для ботов: вход в тестовое окружение, создание тестового бота, запросы к Bot API через /test/ и переключатель TEST в тестере.
Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»
Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».
TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты
Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.
Примеры виджетов Telegram: готовый HTML и код бота на Python
Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.
Виджеты Telegram: интерактивный HTML прямо в сообщениях бота
Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.
Тестирование Telegram Mini App: от браузера до отладки на телефоне
Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.