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, розмітка й кнопки

Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.

Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати

Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.

Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення

Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.

Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму

Як дізнатися chat id у Телеграм через 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.