> Источник: https://apipay.kz/guides/kassir-ne-podklyuchaetsya · Обновлено: 2026-07-06 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

# Кассир Kaspi не подключается — почему и что делать?

**TL;DR.** Чаще всего номер не проходит потому, что у него **есть роли кроме «Кассир»** или на владельца SIM оформлено ИП/ТОО — тогда Kaspi просит пароль или видеоверификацию, которые по SMS пройти нельзя. Первое, что стоит проверить: номер добавлен в **Kaspi Pay → Настройки → Сотрудники** именно с ролью «Кассир», SIM активна и принимает SMS, а на ИИН владельца нет ИП/ТОО в Kaspi Pay. Если это не так — возьмите другой номер.

## Ветки диагностики

| Что видите | Вероятная причина | Что сделать | Подробнее |
|---|---|---|---|
| Kaspi просит **пароль** или **видеоверификацию** | На номере есть роли кроме «Кассира», или на владельца SIM оформлено ИП/ТОО | Взять другой номер: отдельный реальный номер, свободный от бизнеса, только роль «Кассир» | [Требования к номеру кассира](/guides/trebovaniya-k-nomeru-kassira) |
| Просит ввести **ИИН** / «Этого номера нет в Kaspi Pay» | Номер вообще не добавлен в «Сотрудники» | Kaspi Pay → Настройки → Сотрудники → Добавить сотрудника → роль «Кассир», затем начать подключение заново | [Требования к номеру кассира](/guides/trebovaniya-k-nomeru-kassira) |
| **Код из SMS не приходит** или не успеваете ввести | SIM выключена / код истёк / Kaspi ограничил выдачу кодов | Шаги ниже — у этой ветки решение здесь | — |
| Кабинет пишет **«Кассир сейчас недоступен»** | Этот номер подключить нельзя, причина не раскрывается | Повтор с тем же номером не поможет — возьмите другой номер кассира или напишите в поддержку | — |
| Всё по правилам, а подключение падает | Сбой на стороне ApiPay | Написать в поддержку: номер кассира, скриншот экрана Kaspi, время попытки | — |

## Код из SMS: тайминги, о которых надо знать заранее

1. **Код живёт около минуты.** Начинайте подключение, когда телефон кассира физически рядом, SIM вставлена и включена.
2. **Вся авторизация — одно окно ~10 минут.** Ввод номера и ввод кода должны уложиться в него, иначе процесс начнётся заново.
3. **Если Kaspi ограничил выдачу кодов** (`kaspi_busy`, HTTP 503) — пауза около минуты, после неё подключение запускают заново. В кабинете кнопка повтора разблокируется по таймеру сама.
4. **Не передавайте код «по цепочке»** (кассир → бухгалтер → вы): пока код дойдёт, он истечёт. Лучший вариант — телефон кассира у вас в руках.
5. Если SIM была выключена — включите и подождите пару минут: SMS доходят не мгновенно.

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

**Чей номер взять и какой точно подойдёт?**
Разбор с условиями и примерами — [требования к номеру кассира](/guides/trebovaniya-k-nomeru-kassira).

**Как сменить номер кассира на другой?**
См. [смена кассира](/guides/smena-kassira-nomera-vladeltsa).

## Для вашего ИИ-агента

Если подключаете кассира программно, разбирайте ответ `POST /api/v1/connections/{id}/auth/send-phone` (и партнёрский `POST /api/partner/organizations/{id}/kaspi-auth/send-phone`) по `error_code`:

- `not_cashier` — 422, у номера есть роли сверх кассира.
- `not_registered` — 422, номер не заведён кассиром в Kaspi. **Терминально:** сессия закрыта, следующий `send-phone` вернёт `409 no_process`, нужен новый `init`.
- `context_expired` — 409, окно процесса ~10 минут истекло, нужен новый `init`.
- `cashier_unavailable` — 409, кассира сейчас нельзя подключить. Причина не раскрывается, различить её программно нельзя, повтор с тем же номером не помогает: показывайте нейтральный текст и ведите в поддержку.
- `rate_limited` — 429, за сутки пробовали слишком много **разных** номеров кассиров. Окно суточное: `Retry-After` (в партнёрском конверте ещё `retry_after_seconds`) содержит секунды до обнуления счётчика, обычно это часы. Считаются только новые номера: повтор с тем же номером счётчик не расходует, уже подключённые кассиры владельца в него не входят.
- `sms_failed` — 502, Kaspi не вернул экран ввода кода.
- `kaspi_busy` — 503, Kaspi временно не выдаёт код. Пауза около 60 секунд, затем новый `init`. На мерчантской поверхности приходит `Retry-After: 60`; в партнёрском ответе заголовка нет — используйте собственный бэкофф с ориентиром 60 секунд.

Отдельно от них существует поминутный лимит запросов: он отдаёт 429 с телом `{"message":"Too Many Attempts."}` **без** `error_code` и снимается примерно за минуту. Различайте эти два 429 по наличию `error_code`.

На `verify-otp` неверный код — это `200 {"success": false}` и он повторяем, а `not_registered` (422), `context_expired` (409) и `kaspi_busy` (503) терминальны: сессия закрыта, нужен новый `init`. Там же возможен `organization_identity_conflict` (409) — кассир принадлежит другой организации Kaspi. Организация закрепляется за первой привязкой и потом не меняется, поэтому подключать нужно кассира той организации, за которой эта уже закреплена. Если Kaspi не вернул данные организации, приходит `organization_identity_unavailable` (502): попытка закрыта, начните с нового `init`. У обоих в теле только `error` и `message`, поля `error_code` нет.

---

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