Оплата в Stars в своём боте: схема для создателя

Если ваш бот продаёт цифровые товары или услуги — доступ к материалам, генерации, подписку, внутриигровые предметы, — принимать оплату внутри Telegram нужно в Stars. Это не пожелание, а правило платформы. Хорошая новость: схема приёма Stars проще, чем подключение обычного платёжного провайдера. Разберём её по шагам по официальной документации Telegram и отметим места, где разработчики чаще всего ошибаются.

Почему именно Stars

Telegram прямо пишет: оплата цифровых товаров и услуг в ботах и мини-приложениях должна идти только в Stars. Причина — правила магазинов приложений Apple и Google о продаже цифровых товаров. Если бот попытается продавать цифровое за другие валюты или через сторонних провайдеров, Telegram не сможет показывать его пользователям мобильных приложений. Это касается и случаев, когда у вас есть свой сайт с оплатой: внутри Telegram цифровое продаётся за Stars.

Для физических товаров правила другие — там по-прежнему используются обычные платёжные провайдеры.

Что это даёт создателю бота:

• не нужен платёжный провайдер — параметр provider_token для цифровых товаров оставляют пустым;
• покупателю не нужно вводить данные — ни имени, ни адреса, ни карты;
• есть тестовая среда — платежи в Stars можно проверить бесплатно, подключив бота к тестовому окружению Telegram.

Цифровое внутри Telegram продаётся только за Stars. Строить бота в расчёте на обход этого правила — значит рисковать его видимостью в мобильных приложениях.

Схема оплаты по шагам

Валюта Stars в Bot API обозначается кодом XTR. Весь цикл выглядит так.

1. Счёт. Бот отправляет счёт методом sendInvoice с currency: "XTR". В счёте — описание, фото и сумма в Stars. Счёт можно отправить в личный чат, группу или канал. Если бот поддерживает inline-режим, пользователи могут пересылать счёт друзьям.
2. Предварительная проверка. Пользователь нажимает «Оплатить», и боту приходит обновление pre_checkout_query со всеми данными заказа. На него нужно ответить методом answerPreCheckoutQuery в течение 10 секунд — иначе транзакция отменится. Если заказ выполнить нельзя, верните ошибку с понятной причиной: Telegram покажет её пользователю.
3. Подтверждение оплаты. Если всё прошло, приходит сообщение successful_payment. Только после него можно выдавать товар.
4. Сохранение идентификатора. Из successful_payment сохраните telegram_payment_charge_id — он понадобится для возврата.
5. Выдача. Бот доставляет пользователю то, что он купил.

Где чаще всего ошибаются

• Выдают товар после pre_checkout_query. Ответ на предварительную проверку не означает, что оплата прошла. Документация отдельно предупреждает: выдавайте только после successful_payment.
• Не успевают за 10 секунд. Если проверка заказа долгая — запрос к внешней базе, генерация, — оплата отменится. Тяжёлую работу лучше делать после подтверждения.
• Не ограничивают повторные оплаты. Пересылаемые и inline-счета можно оплатить много раз. Бот сам решает, принимать ли новую оплату, и это нужно учесть в логике.

Возвраты и споры

По правилам Telegram, за споры о цифровых покупках отвечает создатель бота. Что для этого нужно:

• бот должен отвечать на команду /paysupport и обрабатывать обращения об оплате;
• возврат делается методом refundStarPayment по сохранённому идентификатору платежа;
• если пользователь добился возврата, Stars списываются с баланса бота;
• если создатель не решает обоснованные споры, Telegram может ввести ограничения — вплоть до списания Stars, удаления бота с платформы и пометки SCAM.

Поэтому идентификатор каждого платежа стоит хранить в базе вместе с заказом, а не только в логах. Без него вернуть Stars не получится.

Куда поступают Stars и когда их можно использовать

Полученные Stars копятся на балансе бота, который виден из аккаунта-владельца. Их можно использовать двумя способами: оплатить рекламу этого бота в Telegram Ads или получить вознаграждение — его выдачу Telegram передал платформе Fragment. Вывод доступен только владельцу и требует пароля двухэтапной проверки.

Важная деталь для планирования: по условиям Telegram для разработчиков, Stars на балансе могут стать доступны для рекламы или вывода не сразу, а в течение до 21 дня после получения. Telegram объясняет это техническими причинами. В том же разделе правил сказано, что Stars могут быть удержаны или списаны с баланса при возвратах покупок.

Если вы сами платите пользователям

Задержка особенно важна, если бот не только принимает Stars, но и раздаёт их — например, награждает за действия. Тогда выплата раньше, чем Stars разблокируются, идёт из вашего кармана. Так устроена, например, биржа заданий Stars Cash Flow: по её описанию, награда исполнителю держится 21 день — ровно столько, сколько у владельца бота разблокируются Stars. Если исполнитель за это время отписался от канала, награда аннулируется, а рекламодатель получает возврат.

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

Telegram приводит свой список требований к боту с оплатой. Сведём его в таблицу вместе с техническими пунктами.

Если вы не разработчик, Telegram советует нанять разработчика или пользоваться сторонним ботом, но с осторожностью: Telegram не поддерживает и не одобряет сторонние боты, которые принимают платежи за других.

Что попробовать

• Официальная документация: платежи в Stars для ботов
• Как устроен холд 21 день на бирже Stars Cash Flow
• Открыть @StarsCashFlowbot