Рахунки Telegram Stars (XTR) у ботах: платіжний процес для розробників крок за кроком
Продаж цифрових товарів за Stars у боті: sendInvoice з XTR, відповідь на pre_checkout_query за 10 секунд, successful_payment, збереження ідентифікатора списання та контрольний список запуску.
Опубліковано:

Ваш бот продає щось цифрове, наприклад підписку, контент, запити до ШІ чи внутрішньоігрові предмети? Тоді оплата лише в Telegram Stars. У цій статті крок за кроком розглянуто процес рахунка Telegram Stars (XTR) з погляду розробника, згідно з офіційною документацією Bot API. Чому це мають бути саме Stars, див. цифрові товари в ботах лише через Stars.
Процес коротко
| Крок | Що робить бот | Що надсилає Telegram |
|---|---|---|
| 1 | sendInvoice з currency = XTR | — |
| 2 | Очікує | pre_checkout_query |
| 3 | answerPreCheckoutQuery (протягом 10 секунд) | — |
| 4 | Очікує | successful_payment |
| 5 | Зберігає ідентифікатор списання, видає товар | — |
Крок 1: створення рахунку
Є два способи:
- Рахунок бота: метод sendInvoice. Оскільки товар цифровий, provider_token — порожній рядок, а поле currency — XTR. Рахунок можна надіслати в приватний чат, групу або канал.
- Вбудований рахунок: якщо бот підтримує вбудований режим, inputInvoiceMessageContent дає змогу ділитися рахунком із друзями, групами й каналами. Його кнопку «Сплатити» можна використовувати багато разів.
Крок 2: вибір поведінки під час пересилання
Це визначає параметр start_parameter:
- Рахунок для багатьох чатів: у пересланих копіях лишається кнопка «Сплатити», тож платити можуть багато користувачів. Вбудовані рахунки завжди для багатьох чатів.
- Рахунок для одного чату: оплатити його можна лише в чаті, куди його надіслано; у пересланих копіях натомість показано кнопку з прямим посиланням на бота.
Зверніть увагу: рахунок для одного чату, надісланий у приватний чат із вашим ботом, можна оплатити лише один раз. У будь-якому разі бот сам вирішує, чи приймати новий платіж.
Крок 3: попереднє підтвердження
Користувач (за потреби спершу купивши Stars) натискає «Сплатити». Бот отримує pre_checkout_query з деталями замовлення і має відповісти через answerPreCheckoutQuery протягом 10 секунд, інакше транзакцію скасують. Якщо відхиляєте, вкажіть зрозумілу причину; Telegram покаже її користувачеві.
Кроки 4–5: оплата і видача
Коли оплата успішна, надходить повідомлення successful_payment. Лише тоді видавайте товар, бо відповідь на pre_checkout_query не гарантує, що платіж пройшов. Збережіть telegram_payment_charge_id; він знадобиться для повернень.
Перед запуском
- Увімкніть двохетапну перевірку для облікового запису, який керує ботом.
- Надайте умови через /terms, а підтримку — через /support і /paysupport.
- Будьте готові до спорів і повернень через refundStarPayment. Докладніше в повернення Stars і /paysupport.
- Тримайте сервер стабільним і робіть резервні копії платіжних даних.
Як тестувати
Окреме тестове середовище Telegram дає змогу безкоштовно тестувати платежі Stars. Коли все працює, переходьте в робоче середовище.
Сторона купівлі Stars
Користувачі купують Stars у застосунку або через @PremiumBot, а PayStars продає їх за USDT. Якщо вашому сервісу потрібно купувати Stars автоматично, це описано в PayStars API та огляді API.
Запитання й відповіді
Чи можна приймати криптовалюту або іншу валюту замість Stars?
Ні. Цифрові товари й послуги в застосунках Telegram оплачуються лише в Stars.
Як тестувати платежі?
Підключіть бота до окремого тестового середовища Telegram, де платежі Stars можна тестувати безкоштовно.
Як оформити повернення?
Методом refundStarPayment в Bot API.
Джерела
Купуйте Stars і Premium за долари США (USDT)
За ключем API: ціна Fragment, 0% (сайт: 5%).
More news
Як написати політику повернення для бота Telegram Stars: шаблон і прикладиЩо має охоплювати політика повернення для бота Telegram Stars: право на повернення, строк, /paysupport і refundStarPayment, а також зразки формулювань, які можна адаптувати.Читати →
Що станеться з вашими Telegram Stars, якщо ви втратите доступ до акаунтаStars належать вашому акаунту Telegram, а не телефону. Дізнайтеся, що з ними станеться, якщо ви втратите доступ, як повернутися та як захистити баланс.Читати →
Ведення обліку доходу від Telegram Stars для автора чи бізнесуЯк вести акуратний облік доходу від Telegram Stars: що записувати, як відстежувати виведення через Fragment, як відокремлювати особисте від бізнесу і про що запитати бухгалтера.Читати →