Перейти к содержимому
← Все статьи
6 мин чтения

Оплата в телеграм боте: архитектура, платежные шлюзы и надежная обработка

Надежная оплата в телеграм боте строится на разделении цифровых и физических товаров, двухэтапном подтверждении транзакций и защите от повторных списаний. Разбираем техническую архитектуру платежей через Bot API.

Разделение цифровых и физических товаров: 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.
  • Формировать итоговую стоимость исключительно на сервере, игнорируя любые клиентские модификации данных корзины.
  • Разделять подтверждение вебхука и тяжелые бизнес-операции через очереди фоновых задач.
  • Сохранять журнал платежных событий с фиксацией идентификаторов транзакций для последующей сверки.
Вопросы

Частые вопросы

Не нашли ответ — спросите на созвоне или в Telegram.

Можно ли принимать рубли через ЮKassa за цифровой контент в боте?

Правила платформы Telegram и требования мобильных магазинов предписывают использовать Telegram Stars для цифровых товаров, электронных подписок и доступа к контенту. ЮKassa и другие фиатные провайдеры применяются для материальных товаров, доставки и офлайн-услуг.

Что произойдет, если бот не успеет ответить на pre_checkout_query за 10 секунд?

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

Хранит ли бот данные банковских карт пользователей?

Нет, бот и сервер разработчика не имеют доступа к платежным данным карт. Ввод и шифрование реквизитов происходят внутри защищенного интерфейса платежного шлюза или Telegram. Бот получает только служебные идентификаторы проведенной транзакции.

Какой платёжный шлюз можно подключить к Telegram-боту?

Для физических товаров и офлайн-услуг бот использует платёжного провайдера в фиатной валюте, подключённого через BotFather, например ЮKassa или Stripe, а в счёте передаётся токен провайдера. Цифровые товары продаются за Telegram Stars (XTR) без токена провайдера. Доступность конкретных провайдеров зависит от страны и их условий, поэтому мы проверяем это до начала разработки.

Связанная услуга

Разработка Telegram-ботов для бизнеса

Бот — это вход в вашу систему там, где клиенты и сотрудники уже общаются. Разрабатываем ботов как полноценные приложения: с базой данных, правами доступа и интеграциями, а не как набор кнопок.

Об услуге
Другие статьи
6 мин чтения

Разработка телеграм бота на заказ: архитектура, интеграции и скрытые затраты

Разработка телеграм бота на заказ: от чего зависит стоимость проекта, выбор между конструктором и кодом, платежи, интеграции, серверы и поддержка.

Читать статью: Разработка телеграм бота на заказ: архитектура, интеграции и скрытые затраты →
6 мин чтения

Разработка Telegram Mini App: архитектура, валидация данных и UX

Разработка Telegram Mini App: когда выбрать веб-приложение вместо бота, проверка initData на бэкенде, приём платежей, работа с WebApp API и требования к UX.

Читать статью: Разработка Telegram Mini App: архитектура, валидация данных и UX →
Контакт

Обсудим вашу задачу?

Тридцать минут созвона — и у вас есть понимание архитектуры, сроков и формата работы. Без обязательств.

Или напишите в Telegram →Читайте наш канал в Telegram →

Укажите Telegram или email, чтобы мы могли ответить.

Отвечаем в течение 15 минут.