Какие есть варианты
| Вариант | Что это | Кому подходит |
|---|---|---|
| «Платежи на Kaspi.kz» | Партнёрство с Kaspi: ваши услуги в приложении Kaspi.kz, подключение по заявке, ответ — в течение нескольких дней | Крупным поставщикам услуг |
| API Магазина на Kaspi.kz | Товары, остатки и заказы маркетплейса Kaspi | Продавцам на маркетплейсе |
| Сервис поверх Kaspi Pay (Aitole) | REST API к вашей кассе Kaspi Pay: QR, счета, ссылки, возвраты, вебхуки | Сайтам, CRM, ботам, SaaS |
Как устроен API Aitole
POST https://api.aitole.kz/v2/invoices
X-API-Key: sk_live_…
Idempotency-Key: order-42
{"amount": 4990, "phone": "+77011234567", "comment": "Заказ №42"}POST /v2/qr— QR и ссылка на оплату для одной покупки.POST /v2/invoices— счёт на номер клиента, придёт ему в приложение Kaspi.POST /v2/refunds— возврат, полный или частичный.- Постоянные ссылки на оплату и регулярные счета — тоже через API.
GET /v2/events— журнал событий: если вебхук не дошёл, ничего не теряется.- Вебхуки
payment.paid,payment.expired,payment.refundedс подписью HMAC-SHA256.
Полное описание — в справочнике API, markdown-версия — docs/index.md.
Что обычно ломается в самописной интеграции — и как это закрыто
- Двойной счёт при повторе запроса. Заголовок
Idempotency-Key: повтор с тем же ключом вернёт тот же счёт. - Отказ Kaspi. Приходит с HTTP 200 и
status: "failed"и понятной причиной — не нужно гадать по кодам. - Сессия Kaspi умерла. Kaspi держит одну сессию на номер; если кассир вошёл в приложение под тем же номером, приём встаёт. Aitole шлёт событие и сообщение в Telegram.
- Несколько касс. Ключ можно привязать к конкретной кассе, чтобы платежи проекта не ушли на соседнюю.
Песочница
Тестовый ключ sk_test_… выдаётся при регистрации. Счета в песочнице не уходят в Kaspi, а статус «оплачено» ставится кнопкой или запросом — проверяется весь путь вашего кода, включая вебхуки.
Если интеграцию пишет ИИ
Дайте ассистенту ссылку на инструкцию для ИИ или полный текст llms-full.txt — там справочник, правила и готовый промпт. ChatGPT, Claude или Cursor соберут интеграцию по ним без догадок об эндпоинтах.