Платежи

Как работают платежи в Telegram

Telegram позволяет ботам принимать оплату прямо в чате. Пользователь видит счёт, нажимает «Оплатить» и вводит данные карты (или платит Telegram Stars) — всё это не выходя из мессенджера.

Для работы платежей нужно:

Подключить платёжного провайдера (Сбербанк, ЮKassa, Stripe и др.) или использовать Telegram Stars.
Добавить блок «Инвойс» в сценарий и настроить товар.

Подключение платёжного провайдера

Получите платёжный токен от выбранного провайдера через @BotFather → Payments.
В конструкторе нажмите «Платёжки» в шапке.
Выберите провайдера из списка и введите полученный токен.
Укажите режим: LIVE (реальные платежи) или TEST (тестовые).
Сохраните подключение.

Одно подключение используется для всех ботов аккаунта.

Блок «Инвойс»

Блок «Инвойс» отправляет пользователю счёт на оплату.

Источник товара

Режим	Описание
Вручную	Заполните название, описание, фото, валюту и позиции цен прямо в блоке. При первой отправке товар автоматически сохраняется в каталог.
Из каталога	Выберите товар из каталога бота. Все данные подтянутся автоматически.
Из переменной	Укажите переменную с ID товара — товар определяется динамически в runtime. Удобно для каталогов, где товар выбирается пользователем.

Провайдер платежей

Режим	Описание
Токен	Вставьте платёжный токен из @BotFather напрямую. Оставьте пустым для оплаты Telegram Stars (XTR).
Провайдер	Выберите из подключённых провайдеров — токен подставится автоматически.

Настройки инвойса

Настройка	Описание
Нода при успехе	Куда перейти после успешной оплаты
Нода при ошибке	Куда перейти при ошибке или истечении времени
Переменная результата	Имя переменной для записи данных платежа (по умолчанию successful)
Таймаут	Сколько минут счёт остаётся активным
Запросить имя / телефон / email	Дополнительные данные от плательщика

Переменные успешного платежа

После успешной оплаты в переменную результата записываются данные транзакции. Если переменная называется successful:

Переменная	Значение
`{{successful.currency}}`	Код валюты (например, RUB)
`{{successful.total_amount}}`	Сумма в копейках/центах
`{{successful.telegram_payment_charge_id}}`	ID транзакции Telegram
`{{successful.provider_payment_charge_id}}`	ID транзакции провайдера
`{{successful.order_info.name}}`	Имя плательщика
`{{successful.order_info.phone_number}}`	Телефон плательщика
`{{successful.order_info.email}}`	Email плательщика

Telegram Stars (XTR)

Telegram Stars — внутренняя валюта Telegram. Пользователь платит звёздами без привязки карты. Для приёма Stars:

Оставьте поле токена провайдера пустым (в режиме «Токен»).
Укажите валюту XTR.
Цены задаются в звёздах (целые числа).

Каталог товаров

Перейдите в «Товары» в шапке конструктора, чтобы управлять каталогом:

Создавайте товары с названием, описанием, фото, ценой и валютой.
Товары доступны в блоке «Инвойс» → режим «Из каталога».
Для каждого товара отслеживается статистика: количество заказов и суммарная выручка.

Советы

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

Внешние платёжные провайдеры

Помимо встроенных Telegram Payments, вы можете принимать оплату через внешние платёжные системы (Tinkoff, FreeKassa, YooKassa, Payeer, Cryptomus, Stripe, PayPal, Robokassa, CryptoBot, Webmoney и др.). Пользователь нажимает кнопку в чате, переходит на страницу оплаты, а после подтверждения бот автоматически выполняет указанную команду.

Подключение внешнего провайдера

В конструкторе нажмите «Платёжки» в шапке.
Перейдите на вкладку «Внешние провайдеры».
Нажмите «Подключить» у нужного провайдера.
Заполните реквизиты (ключи API, идентификаторы магазина и т.д.) — набор полей зависит от провайдера.
Выберите режим LIVE (реальные платежи) или TEST.
Сохраните подключение.

После подключения вы увидите Webhook URL — его нужно указать в личном кабинете платёжного провайдера для приёма уведомлений об оплате.

Кнопка «Ссылка на оплату»

Для приёма оплаты через внешний провайдер добавьте инлайн-кнопку с действием 💳 Ссылка на оплату в любой блок с клавиатурой.

Настройка	Описание
Провайдер	Выберите из списка подключённых внешних провайдеров
Сумма	Сумма платежа. Поддерживает переменные: `{{order_sum}}`
Валюта	Валюта платежа (RUB, USD, EUR и т.д.)
Описание	Текст описания платежа. Поддерживает переменные
Команда при успехе	Нода, которая выполнится после успешной оплаты
Команда при ошибке	Нода, которая выполнится при ошибке (опционально)
Префикс переменной	Имя группы переменных результата (по умолчанию payment)

При нажатии кнопки пользователь получает URL и переходит на страницу оплаты. После подтверждения оплаты провайдером бот автоматически отправляет сообщение из команды при успехе.

Переменные внешнего платежа

После успешной или неуспешной оплаты в переменные записываются данные платежа. Если префикс переменной — payment:

Переменная	Значение
`{{payment.id}}`	Внутренний ID платежа
`{{payment.amount}}`	Сумма
`{{payment.currency}}`	Валюта
`{{payment.status}}`	Статус: paid, failed, pending
`{{payment.order_id}}`	Идентификатор заказа
`{{payment.paid_at}}`	Дата/время оплаты
`{{payment.description}}`	Описание платежа

Визуализация на канвасе

На канвасе конструктора кнопки «Ссылка на оплату» создают визуальные связи:

Зелёная стрелка (💳 … ✓) — путь при успешной оплате
Жёлтая стрелка (💳 … ✗) — путь при ошибке

Советы по внешним провайдерам

Убедитесь, что Webhook URL правильно указан в личном кабинете провайдера.
Используйте режим TEST для отладки — тестовые платежи не проводятся реально.
После успешной оплаты используйте переменные {{payment.*}} для формирования чека или подтверждения.
Добавьте команду при ошибке, чтобы уведомить пользователя о неудачной попытке.

История оплат

Вкладка «Оплаты» в конструкторе (меню «Ещё» в шапке, иконка с купюрой и стрелкой вниз) показывает все платежи, инициированные через кнопку «💳 Ссылка на оплату» — независимо от провайдера и статуса. Это журнал того, что реально проходило по внешним платёжным системам.

Карточки сверху

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

Карточка	Что показывает
Всего платежей	Количество успешно оплаченных платежей с учётом активных фильтров (кроме статуса)
Общая сумма	Суммарный объём оплат по тем же платежам
Платежей сегодня	Количество платежей, оплаченных сегодня
Сумма сегодня	Суммарный объём оплат за сегодня

Колонки таблицы

Колонка	Описание
Даты	Дата создания платежа и дата оплаты (если оплачен) — каждая на своей строке
Order ID	Уникальный идентификатор заказа, сгенерированный платёжкой; ниже — внутренний `#id` и описание
Пользователь	Аватар, имя/фамилия из Telegram, флаг языка, премиум-звезда, кликабельный `@логин` и `#chat_id`
Сумма	`amount` + валюта в верхнем регистре
Провайдер	Логотип и название платёжной системы из «Платёжек»
Payload	Дополнительные данные, переданные в платёж (первые 3 ключа, при наведении — полный JSON)
Статус	Цветной badge: оплачен / ожидание / ошибка / истёк / возврат

Фильтры

Доступны те же типы фильтров, что и в «Подписках», и распространяются как на таблицу, так и на метрики сверху (кроме фильтра статуса — он применяется только к таблице):

Бот — текущий, все боты владельца, или конкретный из списка.
ID — точный внутренний идентификатор платежа.
Order ID — поиск по части идентификатора заказа.
Chat ID — точный chat_id пользователя.
Фамилия / Логин — поиск по полям пользователя в Telegram.
Сумма от/до — диапазон по amount.
Валюта — RUB, USD, EUR и т.п.
Создан от/до — диапазон по дате создания платежа.
Оплачен от/до — диапазон по дате оплаты.
Статус — pending, paid, failed, expired, refunded.
Сортировка — по ID, сумме, дате создания или дате оплаты, по возрастанию/убыванию. Неоплаченные платежи при сортировке по paid_at всегда уходят в конец.