Компоненты 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 неоплаченных счетов — проверяйте количество висящих счетов пользователя перед созданием нового.
- Мульти-бренд ≠ второй аккаунт. Два бота под одним ИП — это просто 2 API-ключа и 2 вебхука в настройках одной организации; создавать дополнительных кассиров для второго бота не требуется. В уведомлении о счёте покупатель видит номер вашего кассира. Что Kaspi показывает рядом — не в нашем контроле; если для второго бренда важна подпись у покупателя, проверьте её тестовым счётом до того, как закладывать вторую SIM.
- Скорость вебхука. Не обещайте пользователю «доступ мгновенно после оплаты» жёстким таймером: доставка статуса обычно занимает секунды, в отдельных случаях — до 10 минут. Правильный UX — «пришлём доступ сообщением, как только Kaspi подтвердит оплату».
- Дубли при ретраях бота. Если ваш код повторяет запрос при таймауте — передавайте
external_order_id_idempotency: повторный POST с тем же ключом получит 409 вместо второго живого счёта.
Частые вопросы
Пользователь должен выходить из Telegram, чтобы оплатить?
Он получает push в приложении Kaspi и оплачивает в один тап. В бота возвращается сам; бот узнаёт об оплате по вебхуку и присылает товар сообщением.
Что если пользователь не оплатил счёт?
Счёт по номеру живёт 24 часа, потом истекает. Неоплаченные счета учитываются в дневном лимите тарифа — поэтому ограничивайте создание счетов на пользователя.
Можно принимать и в Telegram-боте, и в WhatsApp-боте одновременно?
Да, это тот же API: два бота на разных платформах — 2 ключа и 2 вебхука в одной организации.
Сколько это стоит?
Фиксированный тариф по количеству создаваемых счетов в день, без процента с оборота — Тарифы и комиссия.
Возвраты бот может делать сам?
Да, через API (POST /invoices/{id}/refund) либо вручную из кабинета. Возврат уходит с вашего Kaspi-счёта, поэтому на счёте должно хватать денег, а результат приходит вебхуком invoice.refunded, а не в ответе на запрос. Окно возврата и причины отказов — Возвраты Kaspi через API.