Разделение цифровых и физических товаров: Stars и ЮKassa
В Telegram действуют строгие правила выбора платежного инструмента в зависимости от характера товара. Цифровые товары, подписки на закрытые каналы, виртуальные ценности и доступ к функционалу внутри бота или мини-приложения обязаны оплачиваться через Telegram Stars (код валюты XTR). Это требование правил Telegram и магазинов мобильных приложений.
Физические товары и офлайн-услуги подключаются через классические платежные провайдеры, такие как ЮKassa или Stripe. Для них через BotFather настраивается токен провайдера, а расчеты идут в фиатных валютах напрямую между продавцом и эквайрингом. Если вы ещё решаете, нужен ли бот, начните со статьи Telegram-бот для бизнеса.
Создание счета: sendInvoice и ссылки createInvoiceLink
Для выставления счета Bot API предоставляет два механизма: отправку сообщения со счетом через метод sendInvoice или генерацию платежной ссылки через createInvoiceLink. Ссылки удобны для вызова оплаты из Telegram Mini Apps или кнопок веб-интерфейса.
В параметрах счета передаются валюта, список позиций с ценами и служебная строка payload. Параметр payload содержит внутренний номер заказа или идентификатор корзины. Пользователь его не видит, но Telegram возвращает его в каждом ответе, что позволяет сопоставить платеж с записью в базе данных. Оплата внутри Mini App разобрана в статье Telegram Mini Apps.
Двухэтапная обработка: pre_checkout_query и successful_payment
Процесс оплаты в Bot API разделен на предварительную валидацию и подтверждение факта списания:
- pre_checkout_query: Telegram отправляет боту запрос в момент, когда пользователь нажимает кнопку оплаты. Сервер обязан за десять секунд проверить наличие товара, актуальность цены и статус пользователя, после чего вызвать метод answerPreCheckoutQuery с параметром ok=true либо с текстом ошибки.
- successful_payment: после завершения транзакции на стороне банка или системы Stars бот получает сообщение с объектом платежа. В нем содержатся валюта, сумма, исходный payload, telegram_payment_charge_id и provider_payment_charge_id.
Идемпотентность и обработка вебхуков
Telegram доставляет обновления через вебхуки по протоколу HTTPS. Если сервер не вернул HTTP-код 200 вовремя или произошел сетевой сбой, Telegram повторит отправку того же обновления. Без контроля идемпотентности повторная доставка приведет к дублированию выдачи товара или баланса. Разницу между вебхуками и long polling разбираем в статье вебхук или long polling.
Для защиты от дублей идентификаторы telegram_payment_charge_id и provider_payment_charge_id сохраняются в базе данных с уникальным индексом. Обработка успешного платежа и начисление доступа выполняются в единой транзакции, которая проверяет, не была ли транзакция уже обработана ранее.
Механика возврата платежей
Способ возврата средств зависит от используемой валюты. Для платежей в Telegram Stars в Bot API реализован метод refundStarPayment. Для выполнения возврата бот передает идентификатор пользователя и исходный telegram_payment_charge_id, после чего Stars возвращаются на баланс пользователя.
Для фиатных платежей через ЮKassa или Stripe метод refundStarPayment не применяется. Возвраты фиатных средств проводятся вне Bot API: через прямой вызов API платежного шлюза либо через личный кабинет эквайринга по сохраненному provider_payment_charge_id. Платёжная логика входит в факторы стоимости разработки Telegram-бота, а такие боты мы делаем в рамках услуги разработка Telegram-ботов.
Контрольный список безопасности платежного контура
При запуске приема платежей в боте критически важно соблюдать технические требования к безопасности:
- Проверять заголовок X-Telegram-Bot-Api-Secret-Token на вебхуке для подтверждения того, что запрос пришел от Telegram.
- Формировать итоговую стоимость исключительно на сервере, игнорируя любые клиентские модификации данных корзины.
- Разделять подтверждение вебхука и тяжелые бизнес-операции через очереди фоновых задач.
- Сохранять журнал платежных событий с фиксацией идентификаторов транзакций для последующей сверки.