Telegram-бот (@QutPayBot)

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

Мерчанту

Кабинет → Настройки → Telegram-бот → «Получить код привязки» (действует 15 минут, одноразовый).
В личном чате с ботом или в группе, куда добавлен бот, напишите /start КОД (или откройте ссылку и нажмите «Start»).
В этот чат будут приходить: ✅ оплата, ↩️ возврат, ⌛ счета с истёкшим сроком, ⚠️ разрыв сессии Kaspi (со ссылкой на повторный вход).

Команды:

Команда	Что делает
`/invoice 5000`	Счёт с QR/ссылкой; в ответе — страница оплаты, кнопки «Статус», «Отменить»
`/invoice 5000 77001234567 Консультация`	Счёт в приложение Kaspi клиента (на телефон), с описанием
`/today`	Выручка за сегодня, открытые счета
`/last`	Последние 10 счетов
`/status inv_…` / `/cancel inv_…`	Статус счёта / отмена
`/support текст`	Отправить вопрос в поддержку; ответ придёт в этот чат
`/unlink`	Отвязать чат от организации

В личном чате счёт создаётся, даже если просто написать 5000 Урок. Алиасы: /счет, /шот, /бүгін. Счёт может создать любой участник группы — кого добавлять в группу, решаете вы. Возврат из бота не делается (только кабинет/API).

В одно нажатие через WhatsApp

На странице входа «Войти через WhatsApp» → открывается wa.me/<бизнес-номер>?text=Кіру: QP-<id> → клиент отправляет готовое сообщение → Meta webhook (messages) приходит на наш сервер → вход подтверждается по номеру отправителя, клиенту в 24-часовом окне уходит текстовое подтверждение. Шаблон, список тестовых номеров и бизнес-верификация не нужны. В Meta → Configuration → Webhook fields должна быть включена подписка messages.

Вход в кабинет через Telegram

В одно нажатие: на странице входа «Войти через Telegram» → открывается бот → Start → «📱 Отправить мой номер» → страница входит сама (/auth/telegram/start → t.me/бот?start=auth_<id> → контакт → /auth/complete). У того, чей номер уже привязан, контакт не запрашивается. Альтернатива: номер + канал «Telegram» → код приходит в бот.

Администратору платформы

@BotFather → /newbot → токен. Кабинет → Платформа → «Токен платформенного Telegram-бота» → Сохранить (хранится в БД в зашифрованном виде; подойдёт и TELEGRAM_BOT_TOKEN в .env).
«Установить Telegram webhook» — регистрируется API_URL/telegram/webhook (секретный заголовок X-Telegram-Bot-Api-Secret-Token, выводится из TOKEN_SECRET_KEY). При перезапуске сервера повторяется автоматически.
@BotFather → /setprivacy → Disable — чтобы команды /invoice в группе доходили до бота (или сделайте бота администратором группы).
Без https (dev) бот работает в режиме long polling (TELEGRAM_POLLING=1).
Чтобы уведомления приходили вам, на странице Платформа нажмите «Привязать Telegram» → «Открыть бота» (или отправьте боту код /start adm_…, действует 15 мин). Новые регистрации, новые организации, обращения в поддержку, предупреждения о токене/лимитах приходят только привязанным администраторам; непривязанный администратор отображается на странице красным. Эта привязка отделена от номера входа (tg_admin:<phone>), поэтому номер вашего Telegram-аккаунта может отличаться от номера кабинета.

Внутреннее устройство

apps/api/src/services/telegram.js — клиент Bot API, обработка команд, broadcast().
apps/api/src/routes/telegram.js — webhook. panel.js — /panel/orgs/:id/telegram*, /panel/platform/telegram/set-webhook.
Таблицы: telegram_chats (chat → организация), telegram_link_codes. Привязка входа: platform_settings.tg_link:<phone>; уведомления администратора: tg_admin:<phone> (через код), иначе tg_link:<phone>.
Уведомления в notify.js отправляются параллельно в чаты собственного бота организации (settings) и платформенного бота; каждая отправка записывается в таблицу notifications.

Нужна помощь? WhatsApp +77788813333 · kazprose@gmail.com · 09:00–21:00 (Алматы)
Можно написать и из кабинета: Поддержка.

Qut Pay — независимый сервис, не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки правообладателя.