Приём платежей в Telegram-боте: подтверждение платежа и выдача доступа без дублей

Приём платежей в телеграм-боте нельзя сводить к правилу «пользователь нажал кнопку — открыть доступ». Сначала сервер создаёт заказ, затем получает и проверяет подтверждение оплаты, сохраняет его и только после этого запускает выдачу. Если уведомление придёт повторно или выдача прервётся, система должна продолжить незавершённую операцию, а не создать вторую покупку.

Такая схема помогает владельцу процесса заранее разделить ответственность бота, платёжного механизма и серверного обработчика. Она подходит как основа требований к чат-боту с оплатой, но конкретные правила зависят от вида товара и действующих условий Telegram.

Что бот продаёт и какие правила оплаты применимы

Первый вопрос — что именно покупает пользователь. От ответа зависит платёжный сценарий.

Цифровой товар или услуга внутри Telegram. По официальной документации Telegram Bot Payments API for Digital Goods and Services расчёты за такие товары и услуги внутри приложений Telegram должны проходить в Telegram Stars. Для инвойса используется обозначение валюты XTR. Документация отдельно предупреждает, что для этой категории нельзя подменять Stars другой валютой или сторонним платёжным провайдером внутри бота или мини-приложения.

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

Физический товар или относящаяся к нему услуга. Для этого сценария Telegram описывает отдельный поток Bot Payments API с подключением стороннего платёжного провайдера. В нём могут появляться адрес доставки, контактные данные и варианты доставки. Допустимые валюты, провайдер, комиссии и условия продавца проверяют отдельно перед запуском.

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

Как связать заказ и платёж

До отправки инвойса сервер создаёт собственную запись заказа. Минимальная модель содержит:

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

Состав и цену сохраняют на сервере до создания инвойса. Когда приходит платёжное событие, обработчик сопоставляет его с сохранённым заказом. Обычное сообщение пользователя не должно менять ожидаемую сумму, валюту или оплаченный статус.

Участники выполняют разные роли. Бот показывает предложение, собирает предусмотренные сценарием сведения и отправляет инвойс. Для физических товаров расчёт обрабатывает подключённый платёжный провайдер; чувствительные платёжные данные не должны проходить через разработчика бота. Сервер продавца хранит заказ, проверяет событие и управляет выдачей. В сценарии цифрового товара внутри Telegram применяется отдельный механизм Stars, поэтому наличие внешнего провайдера из схемы физических товаров нельзя переносить туда автоматически.

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

Какие события разрешают выдачу

В документированной последовательности Telegram есть три разных этапа.

1. Создание инвойса. Бот предлагает оплатить определённый заказ. На этом этапе деньги ещё не подтверждены, поэтому выдавать доступ нельзя.
2. Предварительная проверка. Сервер получает pre_checkout_query и решает, можно ли принять заказ: существует ли он, совпадают ли условия и доступен ли товар. Положительный ответ разрешает продолжить расчёт, но ещё не доказывает успешную оплату.
3. Успешная оплата. После завершения расчёта Telegram присылает событие с полем successful_payment. Только тогда сервер может перейти к сохранению оплаты и выдаче.

Перед сменой статуса обработчик на сервере сверяет связь события с заказом, валюту и итоговую сумму с сохранёнными значениями. Для цифровой покупки он также проверяет ожидаемую валюту XTR. Цена, состав и статус из сообщения пользователя или других клиентских параметров не заменяют серверную запись.

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

Как выдавать доступ и обрабатывать сбои

Оплату и выдачу лучше хранить как два связанных, но отдельных результата. Сервер сначала атомарно сохраняет уникальный идентификатор подтверждённой транзакции и переводит заказ в состояние paid_delivery_pending. После этого отдельный шаг создаёт право доступа.

Для защиты от дублей нужны два ограничения:

• уникальность идентификатора транзакции — одно подтверждение нельзя записать как две оплаты;
• уникальный ключ выдачи по order_id и типу доступа — один заказ не создаёт два одинаковых права.

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

Пользователь при задержке может увидеть сообщение: «Оплата подтверждена, доступ готовится». Рядом нужен понятный канал помощи человеку и идентификатор заказа, который можно назвать при обращении. Ошибку выдачи нельзя превращать в статус «не оплачено»: иначе покупателю предложат заплатить повторно за уже подтверждённый заказ.

Возврат и спорный платёж образуют отдельный процесс. Для него нужны собственные состояния, связь с исходной транзакцией, журнал действий и правила изменения доступа. Документация Stars предписывает сохранять telegram_payment_charge_id, который может понадобиться для возврата. Конкретное решение о возврате, фискальном оформлении и последствиях для доступа принимает ответственный специалист по правилам продавца и применимым требованиям.

Учебный заказ с повторным платёжным событием

Ниже — синтетический демонстрационный пример по документированной последовательности, а не реальный платёж, файл проверки или клиентский кейс Switch On AI. Все идентификаторы и суммы условны.

Покупатель заказывает один учебный цифровой материал. Цена одной позиции — 250 Telegram Stars. Ожидаемая сумма: 1 × 250 = 250 Stars. В подтверждённом событии указано 250 Stars, поэтому серверная проверка даёт 250 = 250. После неё платёж можно сохранить.

Первая попытка выдать доступ прерывается. Затем обработчик повторно получает событие с тем же условным идентификатором TX-DEMO-001. Уникальность транзакции не позволяет записать вторую оплату. Расчёт остаётся таким: 1 уникальная транзакция × 250 = 250 Stars, а не 500 Stars.

Итог учебной последовательности: один заказ, одна уникальная транзакция и одно право доступа. Повторное событие помогает возобновить незавершённую операцию, но не меняет оплаченную сумму.

Что подготовить для подключения и эксплуатации

До разработки нужно зафиксировать не название «чат-бот — приём платежей», а конкретную операцию и её владельцев:

• кто владеет ботом и учётной записью, кто отвечает за условия продажи и помощь покупателям;
• что продаётся: физический товар, цифровой товар или услуга;
• где совершается покупка и какой платёжный сценарий допустим для этой категории;
• какой провайдер выбран для физического сценария, если он требуется;
• какой тестовый режим или тестовая среда доступны для выбранного пути;
• какие версии, права и ограничения нужно подтвердить на стороне заказчика;
• где работает серверный обработчик событий и как он восстанавливается после недоступности;
• где безопасно хранятся токены и другие секреты;
• какие поля попадают в журнал: заказ, тип события, идентификатор транзакции, результат сверки, попытка выдачи и причина ошибки;
• кто получает уведомление о сбое и как выполняет ручную помощь;
• как резервируются данные о заказах и подтверждённых платежах.

Документация Telegram описывает отдельную тестовую среду для Stars и тестовый режим в сценарии одного из провайдеров для физических платежей. Это не делает их одной настройкой. Доступность конкретного режима, провайдера, тарифа, комиссии и нужных функций следует проверять перед проектом по актуальным условиям и учётной записи заказчика.

ИИ для такого маршрута обычно не нужен: подтверждение суммы, уникальности и статуса должно опираться на строгие серверные правила. ИИ-помощник можно обсуждать отдельно, например для ответов на вопросы покупателей, но он не должен самостоятельно объявлять платёж успешным.

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

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

• успешная оплата с совпадающими заказом, суммой и валютой;
• отклонённая или незавершённая оплата без выдачи доступа;
• несовпадение суммы или валюты;
• событие для неизвестного заказа;
• повтор одного transaction_id;
• два разных подтверждения для одного заказа;
• задержанное событие после закрытия диалога;
• сбой после сохранения оплаты, но до выдачи;
• повторный запуск выдачи после восстановления;
• попытка повторно выдать уже созданное право;
• возврат и согласованное изменение доступа;
• спорный платёж;
• недоступность обработчика и разбор событий после восстановления.

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

Switch On AI может разобрать одну такую операцию и согласовать схему товара, канала, допустимого платёжного сценария, серверного подтверждения и выдачи. На странице разработки чат-ботов описаны границы услуги и подход к проверке подключений. После проверки данных, API, прав и ограничений можно обсудить прототип ключевого сценария — например, обработку подтверждения, дубля и прерванной выдачи.

Чтобы начать обсуждение, укажите площадку, тип продукта и используемый платёжный сервис. Юридические, бухгалтерские и фискальные требования определяет профильный специалист заказчика. Совместимость, тарифы и доступные права проверяются отдельно; прототип не означает готовое внедрение или проведённый платёж.