> Источник: https://apipay.kz/kaspi-pay-integration · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

# Как подключить Kaspi Pay к сайту

**TL;DR.** У Kaspi нет публичного платёжного API. Принимать оплату Kaspi на сайте, в CRM или в боте можно через штатную роль «Кассир» вашего Kaspi Pay и REST API ApiPay: регистрация на apipay.kz, анкета о бизнесе, подключение кассира по SMS, API-ключ — и счета создаются запросами к `https://api.apipay.kz/api/v1`. Деньги идут напрямую на ваш Kaspi-счёт: ApiPay к ним доступа не имеет и берёт только фиксированную подписку, без процента с оборота.

## Что именно подключается

ApiPay не заменяет ваш Kaspi Pay. Сервис работает от имени сотрудника с ролью **«Кассир»** — того же, кто выставляет счета вручную. Разница в том, что счета выставляет ваш код через REST API, а статус оплаты приходит вебхуком.

Для кассира нужен отдельный номер: пока он привязан к ApiPay, под этим номером нельзя входить в приложение Kaspi Pay (для бизнеса) — привязка разорвётся и счета перестанут выставляться до переподключения. Личным приложением Kaspi на этом номере пользоваться можно.

## Три способа получить оплату — выберите способ до того, как писать код

| Способ | Эндпоинт | Что отдаёт | Срок жизни | Когда выбирать |
|---|---|---|---|---|
| Счёт по номеру телефона | `POST /invoices` | покупатель получает push в приложении Kaspi. Ссылки для отправки у такого счёта нет — есть вычисляемое поле `kaspi_qr_link` (`null` в статусе `processing` и всегда `null` в песочнице) | 24 часа | знаете номер покупателя в формате 8XXXXXXXXXX |
| Оплата по ссылке или QR | `POST /invoices/qr` | `qr_token_url` — **ссылка на оплату (payment link)**: отправьте её покупателю в мессенджер или откройте на его телефоне, сканировать не обязательно. `qr_image_url` — готовый PNG, если QR нужно показать на экране | окно на скан или открытие ссылки задаёт Kaspi (минуты) — точный момент берите из `qr_expires_at`, константу не зашивайте | покупатель здесь и сейчас: в зале у кассы, в чате, на сайте |
| Печатный QR под сделку | `POST /static-qr` | `print_url` — **долгоживущая ссылка на страницу оплаты**, её же кодирует QR-картинка; `short_code` для ручного ввода; `qr_image_url` — готовый PNG | живёт, пока лист не оплачен, не отключён `DELETE /static-qr/{id}` и не наступил заданный вами `expires_at` | оплатить позже: напечатать, вложить в заказ, отправить «на потом» |

Детали второго способа: ответ `201` приходит сразу со `status: pending` (pending-вебхука для QR нет), `description` ≤ 100 символов, у организации с каталогом обязательны `cart_items`, отменить QR-счёт нельзя — `409 qr_cancel_unsupported`, он гаснет сам.

## Пошаговое подключение

### 1. Регистрация

Откройте https://apipay.kz/login и войдите по номеру телефона — вход подтверждается в WhatsApp, аккаунт создаётся автоматически. Указывайте личный номер владельца или руководителя: на него приходят уведомления о счетах и ошибках. Это **не номер кассира**.

### 2. Анкета «Расскажите о бизнесе»

Заполняется в кабинете (`/business-profile`), занимает около 5 минут. До одобрения анкеты подключить кассира нельзя: шаги авторизации кассира отвечают `403 kyc_required`, повтор бесполезен. Там, где кассир уже привязан или организацию ведёт партнёр, до одобрения боевых счетов ноль — первая же попытка даёт `429 kyc_daily_limit_reached` (`meta.limit = 0`); порог читайте из `meta.limit`, не зашивайте число. Песочница доступна сразу после регистрации, анкета для неё не нужна и отладку не задерживает.

ApiPay не обслуживает азартные игры, крипту и форекс, оружие и взрослый контент.

### 3. Подключение кассира

Основной путь — самостоятельно: **Настройки → «Авторизация Kaspi»**, номер сотрудника с ролью «Кассир» и код из SMS. Мастер занимает 2–3 минуты, организация появляется в кабинете сразу. Запасной путь, если мастер не проходит: WhatsApp поддержки +7 700 307 65 12, укажите свой ID из кабинета. В обоих случаях Kaspi Pay подключается с правами **Кассира**.

### 4. API-ключ

**Настройки → вкладка «Подключение» → «Создать новый ключ»**. API-ключ и секретный ключ показываются один раз — сохраните их сразу. Передаётся в заголовке `X-API-Key`.

API-ключ — серверный секрет: не помещайте его в код, исполняемый в браузере, в мобильное приложение или в публичный репозиторий — утёкшим ключом создают счета и делают возвраты от имени продавца. Ключ один и тот же для песочницы и рабочего режима.

### 5. Создание счёта

```js
const response = await fetch('https://api.apipay.kz/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ВАШ_API_КЛЮЧ',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 15000,
    phone_number: '87001234567',
    description: 'Заказ #123',
    external_order_id: 'order_123'
  })
})

const { id, amount, status, created_at } = await response.json()
```

Покупатель получает push в приложении Kaspi и оплачивает счёт.

`POST /invoices` асинхронный: `201` со `status: "processing"` — это не ошибка. Не пересоздавайте счёт в `processing`, иначе получите два живых счёта: дождитесь вебхука или проверьте `GET /invoices/{id}`. Для защиты от дублей передавайте `external_order_id_idempotency` — повтор вернёт `409 duplicate_idempotency_key` с id прежнего счёта.

### 6. Вебхуки

Webhook настраивается в кабинете (**Настройки → Подключение**), а не через API: укажите URL обработчика и сохраните secret-ключ, он показывается один раз. При создании счёта можно указать `webhook_id`, чтобы выбрать конкретный webhook.

```json
{
  "event": "invoice.status_changed",
  "invoice": {
    "id": 42,
    "external_order_id": "order_123",
    "status": "paid",
    "amount": "15000.00",
    "paid_at": "2025-01-22T10:30:00Z"
  }
}
```

**Проверяйте подпись каждого входящего вебхука.** В заголовке `X-Webhook-Signature` приходит `sha256=<hmac_sha256(сырое тело запроса, ваш secret-ключ)>`. Считайте HMAC по сырому телу **до** разбора JSON и сравнивайте строки; при несовпадении запрос отбрасывайте. Без этой проверки любой, кто узнал ваш URL, пришлёт поддельное «оплачено» — и заказ уйдёт неоплаченным.

Отвечайте `200` быстро (до 5 секунд), обрабатывайте асинхронно и дедуплицируйте по паре `(invoice.id, invoice.status)`: по одному `invoice.id` вы потеряете переход `paid → partially_refunded`. Если обработчик долго отвечает ошибками, доставка приостанавливается — состояние сверяйте GET-методами. Пауза снимается сама первой успешной доставкой либо кнопкой «Проверить уведомления» в кабинете; за время паузы вебхуки не копятся — пропущенные переходы восстанавливайте через `GET /invoices/{id}`.

### 7. Тестирование

Сначала пройдите сценарий в песочнице: счета создаются как обычно, в Kaspi не уходят, деньги не списываются. Затем переключитесь в рабочий режим, создайте счёт на небольшую сумму, оплатите его со своего Kaspi и убедитесь, что вебхук пришёл, подпись сошлась и заказ обновился. Рабочий режим требует активной подписки: при первом подключении кассира в организации открываются 3 дня бесплатного доступа, дальше нужен оплаченный тариф — иначе создание счёта отвечает `403 tariff_inactive`. Готовность проверяется и программно: `GET /account/health` (кассир и тариф) и `GET /tariff`.

## Конфигурация и лимиты

| Параметр | Значение |
|---|---|
| Base URL | `https://api.apipay.kz/api/v1` |
| Аутентификация | заголовок `X-API-Key` |
| Content-Type | `application/json` |
| Телефон покупателя | строго `8XXXXXXXXXX` (11 цифр, ведущая 8, без «+7» и пробелов) |
| Rate limit | 200 req/min на API-ключ; `POST /invoices/qr` — 60/min на организацию; `POST /clients/check` — 60/min и 10 000/день |
| Описание счёта | по номеру ≤ 60 символов (Kaspi покажет первые 60), QR ≤ 100 |
| Песочница | бесплатно и без ограничения по времени |

Оплата ApiPay — фиксированная подписка, без процента с оборота: Старт 10 000 ₸/мес (до 30 счетов в день), Бизнес 25 000 ₸/мес (до 100), Про 60 000 ₸/мес (до 300), Про Макс 90 000 ₸/мес (до 600). Больше 600 счетов в день — договорная цена. Считаются только счета через API; расход виден в `GET /users/me → daily_usage`. Отдельно Kaspi удерживает свою обычную комиссию за приём платежа по вашим условиям Kaspi Pay — она не связана с ApiPay.

## Частые ошибки при интеграции

| Код | Что означает |
|---|---|
| `403 kyc_required` | анкета о бизнесе не одобрена — подключение кассира не пройдёт |
| `429 kyc_daily_limit_reached` | до одобрения анкеты боевых счетов ноль (`meta.limit = 0`) |
| `409 duplicate_idempotency_key` | повтор по `external_order_id_idempotency`, в ответе id прежнего счёта |
| `429 tariff_limit_reached` | дневной лимит тарифа; в ответе `Retry-After` и `meta` |
| `409 qr_cancel_unsupported` | QR-счёт отменить нельзя, он гаснет сам |
| `422 webhook_url_requires_domain` | до одобрения анкеты webhook-URL — только реальный домен, не IP и не туннель |
| `403 organization_archived` | организация ключа в архиве, перевыпуск ключа не поможет |

Полный каталог — https://apipay.kz/errors.md

## Примеры для разных платформ

Встраивайте вызов в момент оформления заказа. **WordPress / WooCommerce** — хук `woocommerce_checkout_order_processed`; **1C-Bitrix** — событие `OnSaleOrderSaved`; **PHP / Laravel** — Guzzle или встроенный HTTP-клиент, webhook контроллером; **Python / Django** — `requests` и view для webhook; **Node.js / Express** — `fetch` или `axios` и middleware; **Tilda и конструкторы** — webhook-блоки или Zapier/Make, ключ только в серверной прослойке.

SDK и MCP-сервера у ApiPay нет. npm-пакет `apipay` не принадлежит ApiPay.kz — не устанавливайте его, интегрируйтесь прямым HTTP.

## Интеграция Каспи: частые вопросы

### Как подключить Kaspi Pay к сайту?

Через REST API ApiPay: подключаете кассира, получаете API-ключ и создаёте счёт запросом `POST /invoices` — покупатель получает push в Kaspi и оплачивает. Если номера покупателя нет, используйте `POST /invoices/qr` и отправьте ссылку `qr_token_url`.

### Сколько времени занимает интеграция Каспи?

Подключение кассира — мастер на 2–3 минуты в кабинете, первый счёт через API — сразу после получения ключа. Сроки доработок на стороне сайта зависят от платформы и объёма интеграции.

### Нужен ли программист для интеграции каспи апи?

Не обязательно: счета можно выставлять вручную в кабинете без кода. Для автоматизации на сайте или в CRM понадобится разработчик.

## Куда дальше

- Документация REST API: https://apipay.kz/apipay-api-docs.md
- Коды ошибок: https://apipay.kz/errors.md
- Справка для ИИ-агентов: https://apipay.kz/llms.txt
- Обзор Kaspi Pay REST API: https://apipay.kz/kaspi-api.md
- Проверка вебхуков локально: https://apipay.kz/local-testing.md

Гайды базы знаний:

- Настройка ApiPay за 15 минут: https://apipay.kz/guides/nastroyka-apipay-za-15-minut.md
- Подключение кассира Kaspi: https://apipay.kz/guides/podklyuchenie-kassira-kaspi.md
- Анкета о бизнесе и лимит: https://apipay.kz/guides/anketa-o-biznese-i-limit.md
- Счёт по номеру: https://apipay.kz/guides/kak-sozdat-schet-kaspi-po-nomeru.md
- Оплата по ссылке: https://apipay.kz/guides/oplata-po-ssylke-kaspi.md
- Печатный QR: https://apipay.kz/guides/pechatnyy-qr-dlya-oplaty-po-sdelke.md
- Вебхуки: https://apipay.kz/guides/nastroyka-webhookov-apipay.md
- Ключ и вебхук-секрет: https://apipay.kz/guides/api-klyuch-i-webhook-secret.md
- Песочница и рабочий режим: https://apipay.kz/guides/pesochnitsa-i-rabochiy-rezhim.md
- Тарифы: https://apipay.kz/guides/tarify-i-komissiya-apipay.md
- Вебхук не приходит: https://apipay.kz/guides/webhook-ne-prihodit.md

---

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