Как это работает у вас
В терминах бота:
Вход в бота → пользователь вводит номер Kaspi → бот создаёт счёт через API → счёт приходит пользователю push'ем в Kaspi → оплатил → ApiPay шлёт вебхук на ваш сервер → бот выдаёт товар/доступ.
Главный вопрос всех ботоводов — приходят ли деньги сначала к сервису. Нет: ApiPay не выступает посредником в платежах. Деньги идут напрямую на ваш счёт, а сервис берёт только предсказуемую ежемесячную плату в зависимости от количества платежей — без процента с оборота.
Это решает и проблему Telegram Stars: для приёма оплат за пределами Stars вам нужен собственный канал платежей — здесь он идёт напрямую через ваш Kaspi Pay. Нет своего сервера под ботом? Вебхуки ApiPay можно принимать через сценарии n8n — без кода.
Компоненты ApiPay для бота
Боту достаточно нескольких методов Kaspi API; основной инструмент — счёт по номеру:
| Компонент | Зачем боту |
|---|---|
Счёт по номеру (POST /invoices) |
Основной инструмент: пользователь дал номер — получил push; счёт живёт 24 часа |
Вебхук (подпись X-Webhook-Signature) |
Триггер выдачи товара; типовая скорость доставки — секунды–десятки секунд |
Идемпотентность (external_order_id_idempotency) |
Защита от двойного счёта при ретраях вашего бота (повтор → 409) |
| 2 API-ключа + 2 вебхука | Мульти-бренд: два бота на одной организации без второго аккаунта |
| Песочница | Отладка всего флоу без реальных денег |
| Кабинет apipay.kz | Ручные возвраты и контроль счетов, пока бот в разработке |
Пошаговый сетап
- Зарегистрируйтесь на apipay.kz (вход по WhatsApp-OTP на ваш личный номер).
- Отладьте флоу бота в песочнице по документации apipay.kz/docs: счёт → симуляция оплаты → вебхук → выдача. Код — в a15.
- Подключите номер кассира (отдельная SIM, требования — здесь).
- Настройте вебхук и проверку подписи — инструкция. Выдавайте товар только по вебхуку
paid, а не по факту создания счёта. - Добавьте защиту от спама неоплаченных счетов на своей стороне (см. грабли ниже).
- Включите рабочий режим — 3 дня триала на живые тесты, потом тариф по объёму счетов.
Грабли именно ботов
- Тарификация — за выставленный счёт, не за оплаченный. Если бот даёт любому пользователю жать «Купить» без ограничений, неоплаченные счета съедят дневной лимит тарифа. Рекомендуется добавить защиту от спама на своей стороне: например, не давать одному пользователю выставить более 3 неоплаченных счетов. Проверяйте количество висящих счетов пользователя перед созданием нового.
- Мульти-бренд ≠ второй аккаунт. Два бота под одним ИП — это просто 2 API-ключа и 2 вебхука в настройках одной организации. Как только доступ к Kaspi получен, дальнейшая работа идёт целиком через API — создавать дополнительных кассиров для второго бота не требуется. Нюанс: в push-счёте покупатель видит название точки продаж. Если второй бренд должен показываться своим именем — нужен второй кассир во второй точке продаж того же ИП.
- Скорость вебхука. Не обещайте пользователю «доступ мгновенно после оплаты» жёстким таймером: доставка статуса обычно занимает секунды, но у «спящей» организации детект оплаты может занять до ~10 минут. Правильный UX — «пришлём доступ сообщением, как только Kaspi подтвердит оплату».
- Страх «дать код — потерять деньги». Типичное опасение на этапе подключения кассира: не получит ли кто-то доступ к счёту. Роль «Кассир» — штатная роль в Kaspi Pay с минимальными правами: выставить счёт, посмотреть статус, сделать возврат. Доступа к переводам и балансу у неё нет; деньги ApiPay не видит и не держит.
- Дубли при ретраях бота. Если ваш код повторяет запрос при таймауте — передавайте
external_order_id_idempotency: повторный POST с тем же ключом получит 409 вместо второго живого счёта.
Типовой пример: бот с платным доступом
Обобщённый сценарий, с которым чаще всего приходят ботоводы.
Представьте бота, который продаёт платную подписку на контент и раньше принимал оплату только через Telegram Stars. Владелец хочет добавить приём через Kaspi и первым делом уточняет, куда идут деньги. Ответ: ApiPay не выступает посредником — оплата поступает напрямую на счёт продавца, а сервис берёт только фиксированную ежемесячную плату в зависимости от количества платежей.
Дальше владельца интересует сам флоу. Он простой: бот создаёт счёт, счёт приходит покупателю в приложении Kaspi, тот оплачивает, ApiPay подтверждает оплату и присылает вебхук — по нему бот выдаёт доступ.
Отдельный вопрос возникает, когда у одного продавца несколько ботов под разными брендами: нужен ли на каждый бот свой аккаунт. Нет — достаточно одной организации, в настройках которой заводятся отдельные API-ключи и вебхуки под каждый бот. Урок: несколько ботов и брендов спокойно живут на одном аккаунте, а деньги при этом всегда идут напрямую продавцу.
Частые вопросы
Пользователь должен выходить из Telegram, чтобы оплатить?
Он получает push в приложении Kaspi и оплачивает в один тап. В бота возвращается сам; бот узнаёт об оплате по вебхуку и присылает товар сообщением.
Что если пользователь не оплатил счёт?
Счёт по номеру живёт 24 часа, потом истекает. Неоплаченные счета учитываются в дневном лимите тарифа — поэтому ограничивайте создание счетов на пользователя (например, не более 3 неоплаченных).
Можно принимать и в Telegram-боте, и в WhatsApp-боте одновременно?
Да, это тот же API: хоть два бота на разных платформах — 2 ключа и 2 вебхука в одной организации.
Сколько это стоит?
Фиксированный тариф по количеству создаваемых счетов в день, без процента с оборота. Актуальные тарифы — на главной apipay.kz; тестовый период — 3 дня после включения рабочего режима.
Возвраты бот может делать сам?
Да, через API, либо вручную из кабинета. Если возвраты не нужны — просто не встраивайте этот функционал.