# Kaspi Pay REST API — как принимать оплату Kaspi программно

У Kaspi нет публичного платёжного API. Принимать оплату Kaspi программно — на сайте, в Telegram-боте, в CRM — можно через штатную роль «Кассир» вашего Kaspi Pay и REST API ApiPay. ApiPay — независимый сервис поверх вашего собственного Kaspi Pay: деньги идут напрямую на ваш Kaspi-счёт, ApiPay к ним доступа не имеет и комиссию с платежей не берёт — только фиксированную подписку.

## Что даёт REST API ApiPay — 4 способа приёма оплаты

1. **Счета по номеру телефона** — покупатель получает push в приложении Kaspi. Счёт живёт 24 часа, описание ≤60 символов — Kaspi показывает покупателю только первые 60.
2. **QR-счета** — оплата без номера телефона. Окно на скан — меньше трёх минут, точный момент в `qr_expires_at`; описание ≤100 символов.
3. **Вебхуки** — уведомления о статусе платежа в реальном времени. Подпись `X-Webhook-Signature: sha256=<hex>` по сырому телу запроса.
4. **Возвраты** — полный или частичный возврат через API. У счёта нет статуса `refunded`: после возврата остаётся `paid`/`partially_refunded` + `is_fully_refunded`. Возврат уходит покупателю на полную сумму платежа, а свою комиссию за приём Kaspi удержал ещё при оплате — держите на Kaspi-счёте запас, иначе возврат не пройдёт.

Дополнительно — подписки: авто-выставление регулярных счетов. Клиент оплачивает счёт сам, Kaspi не списывает деньги с карты автоматически. Сумма счёта подписки — 100–1 000 000 ₸.

## Конфигурация API

| Параметр | Значение |
|---|---|
| Base URL | `https://api.apipay.kz/api/v1` |
| Аутентификация | заголовок `X-API-Key` |
| Rate Limit | 200 запросов/минуту на API-ключ |
| Content-Type | `application/json` |
| Песочница | бесплатно и без ограничения по времени; счета в Kaspi не уходят |
| Счёт по номеру | живёт 24 часа, описание ≤60 символов |
| QR-счёт | окно на скан меньше трёх минут (`qr_expires_at`), описание ≤100 символов |

`POST /invoices` асинхронный: ответ со `status: "processing"` — это норма, итог придёт вебхуком `invoice.status_changed`, поллинг не нужен. Для идемпотентности передавайте `external_order_id_idempotency` — повтор вернёт `409` с id прежнего счёта.

## Как принимать оплату Kaspi программно

Программный приём Kaspi-платежей работает через штатную роль «Кассир» приложения Kaspi Pay: сотрудник с правами «выставить счёт / посмотреть статус / сделать возврат». Сервис выставляет счета от имени кассира вашей организации, покупатель оплачивает их в своём приложении Kaspi, деньги зачисляются напрямую на ваш Kaspi-счёт. ApiPay даёт к этому механизму REST API.

Для кассира нужен отдельный номер телефона: пока он привязан к ApiPay, под этим номером нельзя входить в приложение Kaspi Pay (для бизнеса) — привязка разорвётся и счета перестанут выставляться до переподключения. Личным приложением Kaspi на этом номере пользоваться можно. Требования к номеру: https://apipay.kz/guides/trebovaniya-k-nomeru-kassira

## Тарифы

Фиксированная подписка без процента с оборота:

- **Старт** — 10 000 ₸/мес (до 30 счетов в день)
- **Бизнес** — 25 000 ₸/мес (до 100 в день)
- **Про** — 60 000 ₸/мес (до 300 в день)
- **Про Макс** — 90 000 ₸/мес (до 600 в день)
- **Больше 600 счетов в день** — договорная цена, напишите нам

Отдельно Kaspi удерживает свою обычную комиссию за приём платежа по вашим условиям Kaspi Pay — она не связана с ApiPay. Тестовый период — 3 дня, песочница бесплатна всегда.

## Частые вопросы

### Как принимать оплату Kaspi на сайте или в Telegram-боте программно?
Через сервис поверх вашего Kaspi Pay: подключается сотрудник с ролью «Кассир», сервис через REST API выставляет счета по номеру телефона или QR, покупатель оплачивает в приложении Kaspi, итог приходит вебхуком. Деньги зачисляются напрямую на ваш Kaspi-счёт.

### Сколько стоит приём оплат Kaspi через ApiPay?
Фиксированная подписка без процента с оборота: Старт — 10 000 ₸/мес (до 30 счетов в день), Бизнес — 25 000 ₸/мес (до 100), Про — 60 000 ₸/мес (до 300), Про Макс — 90 000 ₸/мес (до 600). Больше 600 счетов в день — договорная цена. Отдельно Kaspi удерживает свою обычную комиссию за приём платежа по вашим условиям Kaspi Pay — она не связана с ApiPay. Тестовый период — 3 дня, песочница бесплатна всегда.

### Сколько времени занимает подключение?
Регистрация — пара минут; песочница доступна сразу. Боевые счета — после одобрения анкеты о бизнесе (обычно несколько часов) и подключения кассира по SMS (мастер на 2–3 минуты). При первом подключении кассира включаются 3 бесплатных дня рабочего режима.

## Гайды и документация

- Все гайды по приёму оплат Kaspi: https://apipay.kz/guides/
- Полная документация REST API: https://apipay.kz/docs.html
- OpenAPI 3.0 спецификация: https://apipay.kz/openapi.json
- Для ИИ-агентов: https://apipay.kz/llms.txt

Ключевые гайды:

- Счёт Kaspi по номеру телефона: https://apipay.kz/guides/kak-sozdat-schet-kaspi-po-nomeru
- QR-счёт: TTL и лимиты: https://apipay.kz/guides/qr-schet-ttl-i-limity
- Настройка вебхуков: https://apipay.kz/guides/nastroyka-webhookov-apipay
- API-ключ и вебхук-секрет: https://apipay.kz/guides/api-klyuch-i-webhook-secret
- Возвраты Kaspi через API: https://apipay.kz/guides/vozvraty-kaspi-cherez-api
- Подписки ApiPay: https://apipay.kz/guides/podpiski-apipay
- Оплата Kaspi в Telegram-боте: https://apipay.kz/guides/kaspi-oplata-v-telegram-bote

---

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