Оплата 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, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: 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.