ЮКасса в Телеграм-боте: что проверить перед запуском

ЮКасса в Телеграм-боте, это не просто кнопка “Оплатить”. Рабочий платежный контур должен создать платеж, принять webhook, проверить статус, выдать доступ, записать транзакцию и не сломаться при повторном уведомлении.

Если сделать только красивую кнопку, проблемы появятся после первого реального клиента. Деньги прошли, бот не выдал услугу. Пользователь нажал оплату два раза. Webhook пришёл повторно. Чек нужен, а данных для чека нет.

Из чего состоит платежный контур

• из каких шагов состоит платеж в боте
• почему webhook важнее кнопки оплаты
• какие статусы нужно хранить
• как тестировать платежи до запуска

Сначала опишите, что покупает человек

До подключения ЮКассы нужно понять продукт:

• разовая услуга
• пакет попыток
• подписка
• доступ к файлу
• консультация
• цифровой товар
• пополнение баланса

От типа покупки зависит логика выдачи. Если это разовый файл, бот должен выдать ссылку. Если пакет попыток, нужно увеличить лимит. Если подписка, нужно хранить дату окончания.

В кейсе Телеграм-бот для OCR с монетизацией были бесплатные лимиты, платные пакеты, ЮКасса, согласие по 152-ФЗ и админка. Это уже полноценная продуктовая логика, а не просто платёжная ссылка.

Нормальный платежный маршрут

Минимальный маршрут выглядит так:

1. Пользователь выбирает товар или тариф.
2. Бот создаёт заказ в своей базе.
3. Backend создаёт платеж в ЮКассе.
4. Пользователь переходит на оплату.
5. ЮКасса отправляет webhook.
6. Backend проверяет платеж.
7. Бот выдаёт доступ или меняет лимит.
8. Транзакция записывается в журнал.
9. Пользователь получает понятное сообщение.

Важно, чтобы доступ выдавался не по факту клика, а по подтверждённому статусу платежа.

Webhook может прийти повторно

Платёжные уведомления нельзя обрабатывать как обычное сообщение “один раз пришло, один раз сделали”.

Webhook может прийти повторно. Сеть может упасть. Бот может обработать запрос, но не успеть ответить. Пользователь может нажать кнопку ещё раз.

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

Обычно для этого хранят:

• payment_id
• order_id
• user_id
• статус
• сумму
• валюту
• время создания
• время подтверждения
• raw webhook для диагностики

Чеки и 54-ФЗ нельзя вспоминать в конце

Если нужен фискальный чек, данные для него должны быть в платежном сценарии сразу. Нельзя после запуска внезапно понять, что у товара нет названия, ставки НДС, email или другого обязательного поля.

Список зависит от вашей схемы продаж и настроек ЮКассы. Поэтому в ТЗ нужно написать:

• кто продавец
• что продаётся
• нужен ли чек
• какие данные клиента собираем
• какие товары или услуги попадают в чек
• где хранятся статусы транзакций

Если есть сомнение, платежный контур лучше сначала собрать в тестовом режиме и пройти полный путь.

Что проверить перед запуском

Платёжный бот нельзя проверять только happy path.

Нужны сценарии:

• успешная оплата
• отмена оплаты
• повторный webhook
• повторный клик по оплате
• неверная сумма
• истёкшая ссылка
• пользователь оплатил, потом вернулся в бот
• ошибка выдачи доступа после успешной оплаты

Если бот продаёт подписку, отдельно проверяется окончание срока и продление. В кейсе AI-бот с подпиской в MAX важными частями были статусы пользователей, транзакции, лимиты, email-чек и админский контроль.

Где хранить журнал

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

• кто оплатил
• что купил
• сколько заплатил
• какой статус сейчас
• какой payment_id в ЮКассе
• выдан ли доступ
• была ли ошибка

Без журнала поддержка превращается в гадание. Клиент пишет “я оплатил”, а владелец бота не может быстро проверить, где заказ.

Что сделать в первом MVP

В платежах лучше не начинать с большой витрины тарифов. Первый MVP должен доказать, что бот умеет безопасно принять оплату и выдать результат.

Для этого хватает узкого контура:

1. Один товар или один тариф.
2. Создание заказа в базе.
3. Платёжная ссылка или кнопка.
4. Обработка webhook.
5. Проверка статуса.
6. Выдача доступа.
7. Журнал транзакции.
8. Сообщение пользователю.

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

Для похожих задач обычно достаточно связать платежный контур с разработкой бота и интеграцией с CRM или таблицей. Тогда владелец видит не только факт оплаты, но и кто купил, что получил и где возникла ошибка.

Что показать владельцу после оплаты

После успешной оплаты владелец должен видеть не только сообщение “платёж прошёл”. Ему нужен след, по которому можно быстро ответить клиенту и проверить, что товар или доступ выдан.

Минимально полезный экран или таблица показывает:

• пользователя
• товар или тариф
• сумму
• статус платежа
• статус выдачи доступа
• payment_id
• дату оплаты
• ошибку, если она была

Если продажа связана с подпиской, рядом нужна дата окончания доступа. Если с пакетом попыток, нужен текущий остаток. Если с цифровым товаром, нужна отметка, что ссылка или файл отправлены.

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

Вывод

ЮКасса в Телеграм-боте работает нормально, когда продуман весь платежный маршрут: заказ, платеж, webhook, статус, выдача доступа, чек, журнал и повторные события.

Кнопка оплаты - только видимая часть. Надёжность лежит в backend-логике и проверках, которые пользователь не видит, но сразу чувствует, если они сделаны плохо.