Оплата в Telegram-боте: приём платежей по шагам

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

Варианты приёма оплаты

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

Telegram Stars. Внутренняя валюта платформы. Для части цифровых товаров и услуг внутри мессенджера это обязательный способ по правилам платформы. Разбор - в статье про Stars.

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

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

Схема, которая работает

Порядок шагов, нарушение которого создаёт большинство проблем:

1. Создать заказ в своей базе со статусом «ожидает оплаты». До того, как показывать пользователю счёт.
2. Выставить счёт с указанием идентификатора заказа.
3. Дождаться подтверждения от платёжной системы. Это отдельное событие, а не нажатие кнопки.
4. Проверить, что заказ ещё не оплачен. Если оплачен - выйти, ничего не делая.
5. Отметить оплату и выдать товар.
6. Сообщить пользователю.

Главное в этой схеме - пункт 4. Без него повторное подтверждение выдаст товар второй раз.

Подтверждение платежа

Ключевая мысль: нажатие кнопки оплаты не является оплатой. Фактом является подтверждение от платёжной системы.

Что с этим связано:

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

Подтверждение может прийти дважды. Это штатное поведение при повторной доставке, а не сбой. Отсюда требование идемпотентности.

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

Сумма и валюта сверяются с заказом. Не с тем, что пришло, а с тем, что вы записали при создании заказа.

Идемпотентность

Развёрнуто: повторная обработка одного и того же платежа не должна ничего менять.

Как это делается на практике:

• У заказа есть устойчивый идентификатор, который передаётся платёжной системе и возвращается в подтверждении.
• Перед выдачей проверяется текущий статус заказа. Оплачен - выходим.
• Изменение статуса и выдача происходят в одной транзакции, чтобы не получилось «статус поменяли, товар не выдали».

Тот же принцип в общем виде разобран в блоге: идемпотентные пайплайны.

Что ещё стоит предусмотреть

• Возвраты. Как минимум - ручная процедура и понимание, что происходит с выданным доступом.
• Незавершённые заказы. Пользователь начал и не оплатил. Такие заказы должны истекать, а не висеть вечно.
• Логи всех платёжных событий. При разборе спора вам понадобится история, а не память.
• Разделение сред. Тестовые платежи и боевые не должны ходить в одну базу.
• Отчётность. Что нужно бухгалтерии, стоит выяснить до запуска, а не после первого месяца продаж.

Как это выглядит на реальном проекте - бот продажи курсов. Про Stars - отдельная статья. Обзор - гид по Telegram-ботам.