Telegram Bot API

Оплата Telegram Stars в боте: счета, pre-checkout, возвраты и подписки

· 9 мин чтения

Чтобы принимать оплату в 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 и тратят их в вашем боте; персональные данные форма оплаты не запрашивает. Схема такая:

  1. Бот отправляет счёт: sendInvoice в чат или createInvoiceLink для ссылки.
  2. Пользователь нажимает Pay (при необходимости сначала докупает звёзды).
  3. Бот получает апдейт с pre_checkout_query.
  4. Бот подтверждает или отклоняет заказ через answerPreCheckoutQuery — не позже чем через 10 секунд.
  5. Telegram присылает служебное сообщение с successful_payment.
  6. Бот сохраняет 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 символов.
payload1–128 байт, пользователю не показывается. Храните здесь id заказа или товара: он вернётся в pre-checkout запросе и в платеже.
provider_tokenНеобязательный; для Stars — пустая строка.
currencyXTR.
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 принимает те же 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 секунд, иначе транзакция отменится:

Обработчик должен быть быстрым: проверили 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

Подписки за Telegram Stars

Передайте subscription_period в createInvoiceLink, чтобы списывать оплату каждые 30 дней:

Для платного доступа в канал есть 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. Для запуска в бой переключите бота на рабочее окружение.

Чек-лист перед запуском и типичные проблемы

Только начинаете? Прочитайте, как создать бота в 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.