Ветки диагностики
| Что видите | Вероятная причина | Что сделать | Подробнее |
|---|---|---|---|
| Kaspi просит пароль или видеоверификацию | На номере есть роли кроме «Кассира», или на владельца SIM оформлено ИП/ТОО | Взять другой номер: отдельный реальный номер, свободный от бизнеса, только роль «Кассир» | Требования к номеру кассира |
| Просит ввести ИИН / «Этого номера нет в Kaspi Pay» | Номер вообще не добавлен в «Сотрудники» | Kaspi Pay → Настройки → Сотрудники → Добавить сотрудника → роль «Кассир», затем начать подключение заново | Требования к номеру кассира |
| Код из SMS не приходит или не успеваете ввести | SIM выключена / код истёк / Kaspi ограничил выдачу кодов | Шаги ниже — у этой ветки решение здесь | — |
| Кабинет пишет «Кассир сейчас недоступен» | Этот номер подключить нельзя, причина не раскрывается | Повтор с тем же номером не поможет — возьмите другой номер кассира или напишите в поддержку | — |
| Всё по правилам, а подключение падает | Сбой на стороне ApiPay | Написать в поддержку: номер кассира, скриншот экрана Kaspi, время попытки | — |
Код из SMS: тайминги, о которых надо знать заранее
- Код живёт около минуты. Начинайте подключение, когда телефон кассира физически рядом, SIM вставлена и включена.
- Вся авторизация — одно окно ~10 минут. Ввод номера и ввод кода должны уложиться в него, иначе процесс начнётся заново.
- Если Kaspi ограничил выдачу кодов (
kaspi_busy, HTTP 503) — пауза около минуты, после неё подключение запускают заново. В кабинете кнопка повтора разблокируется по таймеру сама. - Не передавайте код «по цепочке» (кассир → бухгалтер → вы): пока код дойдёт, он истечёт. Лучший вариант — телефон кассира у вас в руках.
- Если SIM была выключена — включите и подождите пару минут: SMS доходят не мгновенно.
Частые вопросы
Чей номер взять и какой точно подойдёт?
Разбор с условиями и примерами — требования к номеру кассира.
Как сменить номер кассира на другой?
См. смена кассира.
Для вашего ИИ-агента
Если подключаете кассира программно, разбирайте ответ 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 нет.