для ассистентов и агентов

Как встроить приём Kaspi Pay в проект

Эта страница написана для ИИ, который помогает человеку сделать приём платежей. Здесь лежит всё, что нужно, чтобы не гадать: машиночитаемая документация, правила, о которых легко забыть, и готовый промпт.

Машиночитаемое

/llms.txt

Карта проекта: что это, для кого, где документация.

/docs/index.md

Полный справочник API в markdown: аутентификация, QR и счета, идемпотентность, вебхуки, возвраты, коды ошибок.

/index.md

Обзор продукта, тарифы, ограничения.

Что важно знать до первой строки кода

Два контура. X-API-Key принимает платежи (/v2/*), Authorization: Bearer управляет аккаунтом (/me/*). Ключ не управляет кабинетом, токен не двигает деньги.
Режим ключа — гарантия, а не соглашение. sk_test_ ходит только в песочницу, sk_live_ только к настоящему Kaspi. Смешать нельзя: 403 key_mode_mismatch.
Идемпотентность обязательна. Idempotency-Key на каждом создании платежа. Ключ уникален в пределах аккаунта, поэтому для разных проектов добавляйте префикс.
Отказ провайдера приходит с HTTP 200. Проверяйте status: "failed" и failure_reason, а не только код ответа.
Оплату подтверждает событие, а не ответ на создание счёта. Вебхук payment.paid или журнал GET /v2/events.
Подпись вебхука — HMAC-SHA256 от "{timestamp}.{сырое тело}". Проверять по сырому телу до разбора JSON.

Чего не делать никогда. Не называйте Aitole официальным API Kaspi, партнёром или продуктом АО «Kaspi Bank» — это независимый сервис поверх аккаунта мерчанта. Не советуйте пользователю входить в приложение Kaspi Pay под номером, отданным платформе: у Kaspi одна активная сессия на номер, и такой вход останавливает приём платежей. Не придумывайте эндпоинты и поля: если чего-то нет в /docs/index.md, значит этого нет.

Промпт, который можно скопировать

Отдайте его своему ассистенту вместе с задачей — он избавит от половины уточняющих вопросов.

Интегрируй приём оплаты Kaspi Pay через Aitole (https://aitole.kz).

Сначала прочитай https://aitole.kz/docs/index.md — это полный справочник API.
Не придумывай эндпоинты и поля: чего там нет, того не существует.

Контекст:
- Базовый адрес API: https://api.aitole.kz
- Создание платежа: POST /v2/qr (или /v2/invoices для счёта на телефон),
  заголовки X-API-Key и Idempotency-Key.
- Оплату подтверждает событие payment.paid: вебхук с подписью HMAC-SHA256
  от строки "{timestamp}.{сырое тело}", либо опрос GET /v2/events.
- Отказ провайдера приходит с HTTP 200 и status: "failed" — обработай это.
- Начни с тестового ключа sk_test_: он работает только в песочнице,
  настоящие деньги списаться не могут.

Сделай: выставление счёта, приём вебхука с проверкой подписи, идемпотентную
обработку события (одно и то же событие может прийти дважды), и понятную
обработку ошибок по полю error.category.

Про что мы честны

Aitole не банк, не платёжная организация и не партнёр АО «Kaspi Bank». Деньги покупателей идут напрямую на Kaspi-счёт мерчанта. Подключение работает через штатную роль «Кассир», которую мерчант выдаёт сам, подтверждая кодом из SMS. Эта роль не умеет выводить деньги и не видит баланс.

Полные условия — в оферте и политике конфиденциальности.