Как принимать оплату звёздами в своём боте
Как сделать оплату звёздами в Telegram-боте: счёт в валюте XTR без платёжного провайдера, ответ на pre-checkout за 10 секунд, возврат звёзд, команда /paysupport и вывод звёзд через Fragment.
Цифровые товары и услуги в ботах Telegram продаются за звёзды. Подключать платёжного провайдера для этого не нужно: счёт в звёздах бот выставляет сам через Bot API, а звёзды приходят на баланс бота.
Почему именно звёзды
По правилам Telegram цифровые товары и услуги в ботах и мини-приложениях оплачиваются только звёздами — этого требуют и правила магазинов приложений. Физические товары можно продавать и за деньги через платёжных провайдеров.
Как выставить счёт в звёздах
- Вызовите
sendInvoice(счёт в чат) илиcreateInvoiceLink(ссылка на оплату). - Укажите валюту
XTR— так в Bot API обозначаются звёзды. - Параметр
provider_tokenоставьте пустой строкой: провайдер для звёзд не нужен. - В
pricesпередайте одну позицию — сумму в звёздах.
Человек увидит счёт, подтвердит оплату, и звёзды спишутся с его баланса.
Читайте также: Как создать бота в ТГ.
Обязательные шаги после оплаты
- pre_checkout_query. Перед списанием Telegram присылает боту запрос. Ответить
answerPreCheckoutQueryнужно в течение 10 секунд, иначе платёж отменяется — пользователь увидит ошибку «bot precheckout timeout». Отвечайте сразу, а тяжёлую работу делайте после ответа. - successful_payment. После оплаты приходит сообщение с
telegram_payment_charge_id. Сохраните его: он нужен для возврата. - Выдача. Выдавайте товар только после
successful_payment.
Возвраты, история и поддержка
- Возврат — метод
refundStarPaymentсtelegram_payment_charge_id: звёзды вернутся покупателю. - История — метод
getStarTransactionsпоказывает зачисления и возвраты бота. - /paysupport — бот обязан отвечать на эту команду: так покупатели спрашивают о платежах.
Подписки и платный контент
- Подписка. В
createInvoiceLinkможно указать период подписки — звёзды будут списываться каждые 30 дней, пока пользователь её не отменит. - Платные фото и видео. Метод
sendPaidMediaприсылает контент, который открывается за звёзды, — как устроено для людей, описано в статье фото и видео за звёзды.
Как вывести звёзды бота
Звёзды копятся на балансе бота — его видно в профиле бота: «Изменить» → «Баланс». Вывести их можно через Fragment — от 1 000 звёзд, и каждая становится доступна через 21 день после получения. Звёздами бота можно оплатить и рекламу в Telegram Ads со скидкой — реклама за звёзды. Пошагово о выводе — в статье как вывести звёзды из бота.
Нужно не принимать звёзды, а отправлять звёзды или Premium своим пользователям? Это делает API бота Shiba Bank — Telegram Stars API.
Частые вопросы
Как подключить оплату звёздами в Telegram-боте?
Выставьте счёт sendInvoice или createInvoiceLink с валютой XTR и пустым provider_token, ответьте на pre-checkout за 10 секунд и выдайте товар после successful_payment.
Нужен ли платёжный провайдер для звёзд?
Нет. Для звёзд provider_token — пустая строка.
Как вернуть звёзды покупателю?
Методом refundStarPayment с telegram_payment_charge_id из сообщения об оплате.
Когда можно вывести звёзды бота?
Через Fragment — от 1 000 звёзд, каждая становится доступна через 21 день после получения.
