ApiPay.kz — плейбук интеграции для ИИ-агентов

Шаг 0. Как себя вести (читает ИИ-ассистент)

• Общайся с клиентом по-русски, простыми словами. Аудитория — владельцы бизнеса 40+, не разработчики. Без жаргона: не «эндпоинт», а «адрес запроса»; не «деплой», а «публикация сайта».
• Останавливайся на пометках «СТОП» (ручные действия человека). Не пиши «готово», пока человек не подтвердил, что шаг выполнен.
• Не выдумывай адреса и поля. Используй только то, что указано в этом документе.
• Иди по шагам строго по порядку. Нельзя создать счёт (шаг 4), пока не пройден шаг 2.
• Песочница не требует кассира Kaspi. Если у клиента ещё нет подключённого кассира — это не повод отказываться писать код или откладывать интеграцию. В тестовом режиме счета создаются и без кассира, деньги не двигаются. Подключение кассира нужно только перед переходом в рабочий режим (шаг 8) — пусть клиент занимается этим параллельно, а ты иди дальше по шагам.
• Официального SDK и MCP-сервера у ApiPay пока нет. Пакеты с похожими именами в npm, PyPI и Packagist — не наши, не устанавливай их. Интеграция делается прямыми HTTP-запросами, как в примерах ниже.

Шаг 1. Объясни клиенту, что такое ApiPay

Передай клиенту своими словами 3 факта:

1. ApiPay — это автоматизация вашего же Kaspi Pay. Мы не банк и не платёжная система. Мы даём программный доступ (API) к приёму платежей через ваш аккаунт Kaspi Pay.
2. Деньги идут напрямую вам в Kaspi. Мы их не храним и не трогаем — только показываем вам и вашему сайту, что клиент оплатил.
3. Комиссии с продаж нет. Оплачивается только подписка на сервис (от 10 000 ₸/мес). При первом подключении кассира — 3 дня бесплатного доступа.

Шаг 2. Проверь предпосылки — ДО написания кода

2a. Кассир Kaspi — нужен только для рабочего режима

Это не блокер для начала интеграции. Новые организации создаются в песочнице по умолчанию — там счета создаются и без подключённого кассира: деньги никуда не идут, всё имитируется. Можно прямо сейчас писать код, создавать тестовые счета и принимать вебхуки.

Кассир Kaspi обязателен только при переходе в рабочий режим (шаг 8): без активной сессии кассира реальные счета будут падать с kaspi_session_not_configured. До этого момента подключение кассира — параллельная задача клиента, она не должна тормозить разработку.

Когда клиент будет готов идти в прод, ему нужно подключить свой Kaspi Pay через сотрудника с ролью «Кассир» — это делается один раз, двумя способами на выбор. Кратко суть (передай клиенту, чтобы запустил это параллельно):

1. Клиент регистрируется на apipay.kz (вход по номеру телефона через WhatsApp). Это обязательно для обоих способов — кассир привязывается к аккаунту ApiPay, без регистрации подключить организацию нельзя. Регистрировать нужно на личный номер владельца/руководителя — на него идут уведомления о счетах и ошибках; это не номер кассира.
2. Клиент берёт отдельный номер телефона (обычная SIM, не виртуальный номер), не привязанный к его личному Kaspi.
3. В приложении Kaspi Pay: Настройки → Сотрудники → добавить сотрудника с ролью «Кассир» на этот номер. Роль должна быть только «Кассир» — не «Управляющий», не «Бухгалтер», не «Менеджер». После добавления Kaspi пришлёт на номер кассира ссылку на скачивание приложения Kaspi Pay — устанавливать ничего не нужно, это сообщение лишь означает, что сотрудник-кассир создан и готов.
4. Способ 1 (основной) — мастер подключения в кабинете. Настройки → вкладка «Авторизация Kaspi» → кнопка подключения, она открывает мастер /settings/connect-cashier. Мастер ведёт по шагам: что такое кассир → три проверки перед привязкой → номер и роль кассира → предупреждение «не заходите в приложение Kaspi Pay под этим номером» → код из SMS → готово. Занимает 2–3 минуты. Сама вкладка «Авторизация Kaspi» — витрина статуса: показывает, подключён ли кассир, когда была последняя активность, и даёт кнопки «Подключить заново» и «Сменить кассира».
5. Способ 2 (запасной) — поддержка. Если мастер не проходит, клиент пишет в WhatsApp +7 700 307 65 12 номер кассира и название организации.
6. Подробная инструкция по обоим способам: apipay.kz/connect-cashier.

Кассирами можно управлять и программно, без кабинета: GET/POST /connections и авторизация кассира POST /connections/{id}/auth/init → auth/send-phone → auth/verify-otp, отключение — auth/logout. Ручки требуют ключа, которому разрешено управление кассирами. Подробности — в llms-full.txt; для обычной интеграции это не нужно, хватит мастера в кабинете.

2b. Где будет жить интеграция — нужен сервер

Определи тип проекта клиента:

• Есть серверная часть (бэкенд) — Node.js, PHP, Python и т.п. → полный сценарий: API + вебхуки. Идём дальше.
• Только статический сайт / конструктор (Tilda, готовый HTML) без сервера → вебхук принять негде. Варианты: (а) добавить минимальную серверную функцию; (б) проверять оплату опросом (polling, см. шаг 5); (в) no-code через n8n.

2c. Анкета о бизнесе и лимит на старте — предупреди клиента заранее

У новых организаций есть мягкий лимит на старте: пока не заполнена и не одобрена короткая анкета «Расскажите о вашем бизнесе», в рабочем режиме можно создать 1 реальный счёт в сутки. В песочнице лимита нет — тестируй сколько нужно, разработку это не тормозит.

Зачем это нужно (объясни клиенту причину): это разовая проверка, по итогам которой лимиты на приём платежей настраиваются под обороты клиента.

Что сделать: клиент заполняет анкету в кабинете на /business-profile (~5 минут: что продаёт, где продаёт, средний чек). Одобрение обычно за 1 рабочий день — после него лимит снимается автоматически. При попытке создать второй счёт за сутки API вернёт 429 kyc_daily_limit_reached (в meta.reset_at — когда лимит сбросится). Это не блокер разработки: продолжай в песочнице.

Шаг 3. Получи доступы в личном кабинете

Это делает человек в кабинете на apipay.kz. Нужно войти под ролью Владелец или Разработчик — у роли «Менеджер» доступа к ключам нет. Точный путь по меню:

Мастер создания ключа — 4 шага

1. Настройки → вкладка «Подключение» → кнопка «Создать новый ключ». Открывается мастер.
2. Шаг 1. Назовите ключ — понятное имя: «Мой сайт», «Telegram-бот», «Программа магазина».
3. Шаг 2. Куда сообщать об оплате — поле «Адрес для уведомлений»: публичный адрес обработчика на сайте клиента, например https://ваш-сайт.kz/webhooks/apipay. Это и есть «webhook URL». Шаг можно пропустить и вписать адрес позже.
4. Шаг 3. Защитим уведомления — секретный ключ подписи (webhook secret) выпускается автоматически, искать и придумывать ничего не нужно.
5. Шаг 4. Готово! Сохраните данные — API-ключ и секрет показываются один раз. На этом экране есть кнопка «Скопировать всё для ИИ-помощника»: она кладёт в буфер обмена сразу API-ключ, адрес для уведомлений и секрет вместе с пояснением, что с ними делать.

Если ключ уже создан раньше

• Изменить адрес для уведомлений — на карточке ключа кнопка «Изменить».
• Секрета нет (в карточке «Не настроено») — меню «Ещё» → «Создать секретный ключ подписи». Секрет тоже показывается один раз.

Сохрани значения в переменные окружения сервера (никогда — в репозиторий):

APIPAY_API_KEY=...
APIPAY_WEBHOOK_SECRET=...
APIPAY_BASE_URL=https://api.apipay.kz/api/v1

Шаг 4. Встрой получение оплаты — три способа

Какой способ выбрать

Сценарий клиента → способ

Лимиты запросов

Каждый ответ несёт X-RateLimit-Limit и X-RateLimit-Remaining. При превышении приходит 429 с заголовком Retry-After и полем retry_after_seconds в теле — жди указанное число секунд, а не повторяй сразу. Заголовки показывают тот счётчик, где осталось меньше всего, поэтому сравнивай Remaining с Limit из того же ответа, а не с числом из таблицы.

Способ 1. Счёт по номеру телефона — POST /invoices

// выполняется на сервере
const res = await fetch('https://api.apipay.kz/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.APIPAY_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '87001234567',     // обязательно. Формат строго 8XXXXXXXXXX (11 цифр)
    amount: 15000,                   // обязательно. Сумма в тенге, только целая
    description: 'Заказ №123',       // необязательно, до 60 символов
    external_order_id: 'order_123'   // необязательно — ваш ID заказа для сверки
  })
})
const invoice = await res.json()
// → { id: 42, amount: "15000.00", status: "processing", paid_at: null,
//     phone: "87001234567", is_imported: false, created_at: "2026-09-03T12:00:00+00:00" }
// amount — СТРОКА, не число. paid_at заполнится после оплаты.
// is_imported: true — продажа подтянута из истории Kaspi (проведена в приложении мимо ApiPay).

Клиент получит уведомление в приложении Kaspi и оплатит там. Сохрани invoice.id рядом со своим заказом. Часть полей ответа условная — они появляются, только когда есть значение (subtotal и discount_sum при скидке или корзине, error_message при статусе error).

Ссылка у счёта по номеру. У такого счёта нет ссылки, которую можно отправить покупателю как приглашение к оплате — он приходит push-уведомлением. В ответах GET /invoices/{id} есть поле kaspi_qr_link: это ссылка на оплату именно этого счёта, из неё можно нарисовать QR-код. Она null, пока Kaspi не присвоил счёту свой идентификатор (то есть в статусе processing), и всегда null в песочнице — на неё нельзя рассчитывать как на основной канал доставки. Нужна ссылка сразу и наверняка — бери POST /invoices/qr.

Способ 2. Оплата по ссылке или QR — POST /invoices/qr

// выполняется на сервере. Телефон покупателя НЕ нужен.
const res = await fetch('https://api.apipay.kz/api/v1/invoices/qr', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.APIPAY_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 15000,                   // сумма; тиыны здесь принимаются
    description: 'Заказ №123',       // необязательно, до 100 символов
    external_order_id: 'order_123'
  })
})
const qr = await res.json()
// → { id: 77, amount: "15000.00", status: "pending", phone: null, is_qr_token: true,
//     qr_token_url: "https://qr.kaspi.kz/...",   // ССЫЛКА НА ОПЛАТУ — отправьте покупателю
//     qr_image_url: "https://.../qr.png",         // тот же счёт картинкой, для экрана кассы
//     qr_expires_at: "2026-09-03T12:03:00+00:00" }

// Отправляем ссылку покупателю в мессенджер — сканировать ничего не нужно:
// на телефоне с приложением Kaspi по ссылке откроется готовый счёт.
await sendToCustomerChat(`Оплатите заказ №123 по ссылке: ${qr.qr_token_url}`)

• Окно на оплату задаёт Kaspi. Считай его из qr_expires_at, не зашивай числом в код. qr_expires_at ограничивает момент, когда покупатель ещё может открыть счёт; оплата, начатая под конец окна, завершится и позже. Терминальный статус ставит Kaspi — ориентируйся на вебхук, а не на свой отсчёт.
• qr_image_url живёт до qr_expires_at плюс минута, потом отдаёт 404. Это значит «выпусти новый счёт», а не «перезагрузи картинку».
• Отмены нет. POST /invoices/{id}/cancel для такого счёта вернёт 409 qr_cancel_unsupported. Возврат делается отдельной веткой: ссылка покупателю POST /qr-refunds/links, затем POST /qr-refunds/{id}/execute (POST /qr-refunds — deprecated).
• Песочница отменяет QR-счёт, бой — нет. В тестовом режиме POST /invoices/{id}/cancel ответит 200 и переведёт счёт в cancelled; в рабочем — 409 qr_cancel_unsupported. Не проверяй ветку отмены на песочнице.
• Такие счета сосуществуют: новый не отменяет прежние. Реагируй по каждому invoice.id отдельно.
• Когда покупатель открыл счёт, приходит событие invoice.qr_scanned (qr_substate: "scanned"), статус при этом остаётся pending. Это ещё не оплата — товар отдавай только по paid.
• У организации с каталогом вместо amount нужен состав: cart_items. Без него придёт 422 catalog_requires_cart_items (см. шаг 4.5).

Способ 3. Печатный QR под сделку — POST /static-qr

const res = await fetch('https://api.apipay.kz/api/v1/static-qr', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.APIPAY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: 15000,                  // целая сумма: лист умеет и оплату по номеру телефона
    description: 'Договор №14',     // до 100 символов
    external_order_id: 'deal_14',
    single_use: true                // одна сделка: после оплаты скан покажет «Оплачено»
  })
})
const sheet = await res.json()
// → { id, token, short_code: "K7M9P2Q4", print_url: "https://qr.apipay.kz/...",
//     manual_url, qr_image_url, status: "active", paid: false }
// print_url — долгоживущая ссылка: печатайте её QR-кодом ИЛИ отправляйте в мессенджер.

• Kaspi при выпуске листа не вызывается — счёт создаётся в момент, когда покупатель откроет ссылку. Деньги и вебхук приходят вам штатно.
• Всё, что сделало бы скан нерабочим (нет cart_items у организации с каталогом, чужая позиция каталога, неоднозначный кассир, слишком длинное описание), отбивается при выпуске, а не при скане. Переиздать напечатанный лист нельзя.
• Отключить лист — DELETE /static-qr/{id}: новые сканы покажут «неактивно», уже созданные счета не трогаются.

Проверить статус — GET /invoices/{id}

Жизненный цикл статуса: processing → pending → paid (или cancelled / expired / error). После частичного возврата оплаченный счёт становится partially_refunded, после полного — refunded. Счёт из POST /invoices/qr появляется сразу в pending, минуя processing. Массовая проверка нескольких счетов сразу — POST /invoices/status/check с телом {"invoice_ids":[1,2,3]}.

Шаг 4.5. Залей каталог — если в чеке нужны позиции (опционально)

Этот шаг нужен, только если клиент хочет видеть в чеке Kaspi позиции (название, цена, количество), а не одну сумму. Если продаёте «на сумму» — пропусти шаг и оставайся на обычном POST /invoices.

1. Скан штрихкода — POST /catalog/scan (только для маркированных)

// выполняется на сервере
const scan = await fetch('https://api.apipay.kz/api/v1/catalog/scan', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.APIPAY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ input: '4870000000001' })  // штрихкод
})
const { data } = await scan.json()
// data[] — кандидаты { id, name, ntin, gtin, barcode, unit_id }. Пустой data[] = товар
// не из Нацкаталога — это НЕ ошибка, заводи без ntin/gtin.

2. Залить товары — POST /catalog (от 1 до 100 позиций)

const res = await fetch('https://api.apipay.kz/api/v1/catalog', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.APIPAY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [
      { name: 'Ручка гелевая синяя 0.5', selling_price: 350, unit_id: 1,
        barcode: '4870000000001', external_ref: '1c-000123' },  // external_ref = ключ маппинга
      { name: 'Тетрадь 48 листов клетка', selling_price: 420, unit_id: 1,
        barcode: '4870000000002', external_ref: '1c-000124' }
    ]
  })
})
// Ответ ВСЕГДА 202 — и в песочнице, и в рабочем режиме.
// { data: [...], rejected: [...] } — ключ rejected есть всегда, может быть пустым.

3. Подтвердить результат

Ответ 202 — «принято», не «готово». В песочнице позиция возвращается уже активной, в рабочем режиме получает pending и уезжает в Kaspi фоном. Финальный статус (active/failed) узнаётся одним из двух равноправных путей:

// Путь A (просто, для 1С/on-prem): поллинг по external_ref
const check = await fetch('https://api.apipay.kz/api/v1/catalog?' +
  'external_refs[]=1c-000123&external_refs[]=1c-000124',
  { headers: { 'X-API-Key': process.env.APIPAY_API_KEY } })
const items = (await check.json()).data
// status: 'active' — товар в Kaspi; 'failed' — смотри error_code.

// Путь B (SaaS с публичным URL): вебхук catalog.item_processed приходит на твой webhook_url
// с полями { id, external_ref, kaspi_item_id, status, operation, error_code, ntin_missing }.

Продажа с каталогом: в POST /invoices, POST /invoices/qr и POST /static-qr вместо amount передавай cart_items: [{ catalog_item_id, count }] — где catalog_item_id это id товара из каталога. У организации с каталогом POST /invoices/qr и POST /static-qr без cart_items отвечают 422 catalog_requires_cart_items.

Шаг 5. Принимай вебхук об оплате

Когда счёт оплачен, ApiPay сам отправляет POST на твой адрес вебхука. Тело события:

{
  "event": "invoice.status_changed",
  "invoice": {
    "id": 42,
    "external_order_id": "order_123",
    "amount": "15000.00",
    "status": "paid",
    "paid_at": "2026-09-03T08:35:00Z"
  },
  "source": "имя вашего ключа",
  "timestamp": "2026-09-03T08:35:01Z"
}

Все события — что приходит и что нужно типовой интеграции

Технические статусы processing и cancelling вебхуков не порождают никогда — не жди их.

Проверка подписи — обязательно

Каждый вебхук содержит заголовок X-Webhook-Signature: sha256=<hex> — это HMAC-SHA256 от сырого тела запроса с секретом вебхука.

const crypto = require('crypto')

// rawBody — НЕОБРАБОТАННОЕ тело запроса (Buffer/строка), НЕ результат JSON.parse.
// В Express: app.post('/webhooks/apipay', express.raw({ type: 'application/json' }), ...)
function verifyWebhook(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  const got = Buffer.from(signature || '')
  const exp = Buffer.from(expected)
  if (got.length !== exp.length) return false
  return crypto.timingSafeEqual(exp, got)
}

Повторные доставки и идемпотентность

Если твой сервер не ответил 2xx за 5 секунд (плюс до 3 секунд на соединение), ApiPay повторит доставку. Всего до 11 попыток (первая + 10 повторов) с нарастающей задержкой: 10с, 30с, 1м, 1.5м, 2м, 5м, 10м, 15м, 30м, 1ч — около 2 часов. 5xx/429/таймаут → повтор; прочие 4xx → без повтора.

Если сервера нет (шаг 2b) — вместо вебхука опрашивай статус: периодически вызывай GET /invoices/{id}, пока не будет paid. Опрос полезен и при наличии вебхука — как сверка, если все попытки доставки не прошли.

Шаг 6. Протестируй интеграцию

Тестируй в тестовом режиме (песочнице) — счета не уходят в реальный Kaspi, деньги не двигаются. Новая организация в песочнице по умолчанию.

1. Проверка вебхука. Попроси клиента в кабинете (Настройки → «Подключение», карточка ключа) нажать кнопку «Проверить уведомления» — ApiPay пошлёт на адрес тестовое событие webhook.test. Убедись, что твой обработчик его принял и подпись сошлась.
2. Проверка оплаты. Создай тестовый счёт через POST /invoices. В песочнице оплату счёта имитируют из кабинета: страница «Счета», у тестового счёта кнопка «Симулировать». Попроси клиента это сделать; придёт вебхук invoice.status_changed со статусом paid.
3. Убрать тестовые данные. Кнопка «Очистить тестовые данные» есть на каждой странице отдельно — «Счета», «Каталог», «Подписки». Общей кнопки «очистить песочницу» в настройках нет. Рядом есть «Заполнить тестовыми данными».
4. Локальная разработка. Если сервер пока на localhost, ApiPay до него не достучится — подними туннель (ngrok). Инструкция: apipay.kz/local-testing. Туннель годится только для теста в песочнице: рабочий вебхук должен быть на реальном домене (см. шаг 8).

Полностью автономный тест через API (без человека)

Если у тебя есть sandbox-ключ (X-API-Key тестовой организации, is_sandbox: true), весь цикл можно пройти программно — не дёргая человека в кабинете. Два инструмента песочницы:

• POST /invoices/{id}/simulate-status — переводит sandbox-счёт из pending в paid/cancelled/expired/error или симулирует событие qr_scanned (для счёта по ссылке или QR). Работает ТОЛЬКО в песочнице; боевой счёт всегда вернёт 403 not_sandbox. Отдельный лимит — 60 запросов/мин на ключ.
• GET /webhook-logs и GET /webhook-logs/{id} — read-only логи доставки: программно проверяешь, что вебхук ушёл и приёмник ответил 2xx (фильтры invoice_id, event, status).

# Полный автономный цикл (sandbox X-API-Key). Требуется jq.
KEY="YOUR_SANDBOX_API_KEY"; BASE="https://api.apipay.kz/api/v1"

# 1. Создать sandbox-счёт (external_order_id_idempotency защищает от дублей при ретрае)
ID=$(curl -s -X POST "$BASE/invoices" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"phone_number":"87770000001","amount":5000,"description":"Autotest","external_order_id_idempotency":"autotest-001"}' | jq -r '.id')

# 1a. Дождаться статуса pending — счёт создаётся в processing, переход асинхронный
#     (обычно 1-3 секунды); simulate-status требует pending. Поллинг раз в 1-2 сек.
#     (Счёт из POST /invoices/qr сразу pending — для него шаг не нужен.)
until [ "$(curl -s "$BASE/invoices/$ID" -H "X-API-Key: $KEY" | jq -r '.status')" = "pending" ]; do sleep 1; done

# 2. Симулировать оплату
curl -s -X POST "$BASE/invoices/$ID/simulate-status" -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"status":"paid"}'

# 3. Проверить доставку вебхука invoice.status_changed (status: paid)
#    Если ответ пуст — проверьте по ?invoice_id=$ID без event; тип события есть в request_body.
curl -s "$BASE/webhook-logs?invoice_id=$ID&event=invoice.status_changed" \
  -H "X-API-Key: $KEY" | jq '.data[] | {event, status, response_status}'

# 4. Частичный возврат (paid → partially_refunded, в песочнице без Kaspi)
curl -s -X POST "$BASE/invoices/$ID/refund" -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"amount":2000}'

# 5. Проверить вебхуки возврата: invoice.refunded + invoice.status_changed (partially_refunded)
curl -s "$BASE/webhook-logs?invoice_id=$ID" -H "X-API-Key: $KEY" | jq '.data[] | {event, status}'

# Другие ветки (каждая — новый sandbox-счёт, дождаться pending как в шаге 1a):
#   {"status":"cancelled"}  → invoice.status_changed (cancelled)
#   {"status":"expired"}    → invoice.status_changed (expired)
#   {"status":"error","error_message":"Тест"} → error_code: sandbox_simulated_error
# Оплата по ссылке или QR: POST /invoices/qr с телом {"amount":5000,"description":"QR autotest"}
#   (phone_number не нужен; счёт сразу pending, в ответе qr_token_url) + {"status":"qr_scanned"} →
#   invoice.qr_scanned (qr_substate: scanned, статус остаётся pending;
#   повторный qr_scanned → 400 already_scanned)

Sandbox-вебхуки по счетам доставляются с 3 попытками (задержки 5с/15с; в рабочем режиме — до 11 попыток ~2ч), успех — любой HTTP 2xx. Критерий успеха теста: по каждому шагу в /webhook-logs есть ожидаемое событие со status: success. Готовый копипаст-промпт для тест-агента — на apipay.kz/prompts.

Шаг 7. Отладка

Счёт не создаётся — таблица ошибок POST /invoices

Полный каталог кодов ошибок с пометкой, какие имеет смысл повторять, — apipay.kz/errors.md (человеку удобнее apipay.kz/errors).

Счёт создался (201), но статус стал error

Создание счёта по номеру телефона асинхронное: POST /invoices возвращает 201 со статусом processing, дальше счёт уходит в Kaspi в фоне. Если что-то пошло не так на стороне Kaspi — это не ошибка HTTP, а статус error у счёта. Проверяй через GET /invoices/{id}:

• status — стал error;
• error_code — стабильный машиночитаемый слаг причины. По нему и строй switch-логику;
• error_message — та же причина текстом, только для показа человеку. Не завязывай логику на подстроки этого текста — он может меняться.

Например client_not_found — номер не зарегистрирован в Kaspi (попроси клиента дать номер с установленным приложением Kaspi, повтор не поможет); network_unavailable — Kaspi временно недоступен (повтори создание счёта позже). Полный список слагов и их retryable-разметку смотри в errors.md.

Сессия кассира Kaspi (kaspi_session_invalid, kaspi_session_expired)

Сессия кассира рассчитана на долгую работу — ежедневно или по расписанию переподключать кассу не нужно. Прерваться она может, например, если кто-то вошёл в Kaspi или Kaspi Pay под номером кассира либо Kaspi сбросил сессию на своей стороне. Ретраи запроса не помогут: владелец организации один раз переподключает кассу по SMS — кабинет, Настройки → «Авторизация Kaspi» → кнопка подключения, либо через поддержку. Инструкция: /connect-cashier. Программно состояние сессии видно в GET /account/health → connection.needs_reauth — так «сессия слетела» ловится опросом, без вебхука.

Оплата прошла, но подтверждение не пришло

Открой в кабинете Настройки → «Лог уведомлений» — там видно каждую отправку вебхука: адрес, HTTP-код ответа твоего сервера, отправленное тело и полученный ответ. Это главный инструмент диагностики:

• Код ответа не 2xx → твой обработчик упал. Частые причины: не та проверка подписи (нужно сырое тело), ответ дольше 5 секунд, ошибка в коде.
• Отправок вообще нет → не указан адрес вебхука на ключе (шаг 3), счёт создан другим ключом, либо уведомления по этому ключу поставлены на паузу (см. ниже).
• Адрес — localhost → ApiPay до него не достучится, нужен туннель (шаг 6).
• В логе redirect not followed → адрес отвечает переадресацией 301/302. Такие переходы теряют тело запроса, поэтому доставка считается неуспешной. Указывай сразу конечный адрес на https://.

После ответа 4xx (кроме 429) автоматических повторов нет вовсе: попытка считается неуспешной, и этот переход больше сам не отправится. Переслать его можно только вручную — в кабинете, «Лог уведомлений», кнопка повтора у неудачной записи.

Шаг 8. Переход в рабочий режим

Когда тесты в песочнице прошли:

Предполётная проверка — программно, до разговора с клиентом

// Два GET-запроса показывают, готов ли аккаунт к рабочему режиму.
const health = await (await fetch('https://api.apipay.kz/api/v1/account/health',
  { headers: { 'X-API-Key': process.env.APIPAY_API_KEY } })).json()
// connection — подключён ли кассир и жива ли сессия (connection.needs_reauth),
// tariff.status — активна ли подписка, invoicing.accumulating — копятся ли счета.

const tariff = await (await fetch('https://api.apipay.kz/api/v1/tariff',
  { headers: { 'X-API-Key': process.env.APIPAY_API_KEY } })).json()
// снимок подписки клиента на ApiPay: срок, суммы. Это плата за сервис, не оборот клиента.

Оба запроса — только чтение, лимитов тарифа не расходуют и работают даже при неактивной подписке. Если tariff.status не активен или кассир не подключён — не отправляй клиента переключать режим, сначала закрой эти пункты.

1. Кассир Kaspi подключён по /connect-cashier, подписка оплачена (при первом подключении кассира — 3 дня бесплатно).
2. Анкета о бизнесе заполнена на /business-profile (~5 мин). До её одобрения молодая орг создаёт лишь 1 реальный счёт/сутки (429 kyc_daily_limit_reached) — заполни заранее, чтобы к запуску лимит уже сняли. Зачем это — см. шаг 2c.
3. Адрес вебхука — на реальном домене (публичный HTTPS, не IP и не туннель). Для ещё не одобренной орг ngrok/IP в проде дадут 422 webhook_url_requires_domain/webhook_url_tunnel_forbidden. Туннель из шага 6 — только для теста в песочнице.
4. Переключение режима — баннер в шапке раздела «Настройки», над всеми вкладками. Там написано «ТЕСТОВЫЙ РЕЖИМ» и стоит кнопка «Переключить в рабочий режим». Кнопка доступна ролям Владелец и Разработчик; режим можно менять не чаще раза в 5 минут.
5. В рабочем режиме счета уходят в реальный Kaspi, клиенты платят настоящими деньгами.

Готово — интеграция приёма платежей завершена.

Шаг 9. Касса Kaspi — смены, наличные, сверка (опционально)

Нужно, если у клиента есть касса Kaspi и он хочет закрывать смены, забирать отчёты и сверять кассу со счетами не руками. Требует подключённого кассира (шаг 8) и активной подписки; у кассовых ручек отдельный лимит — 30 запросов в минуту на ключ.

Проверьте предусловие до того, как писать код. Кассовые ручки работают только у организаций, к аккаунту Kaspi Pay которых подключена Kaspi Касса (ОФД) — та же связка, что включает каталог товаров. Если клиент принимает оплаты через Kaspi Pos без ОФД, кассовых смен у него не существует: раздел «Касса» в кабинете не показывается, а ручки отвечают 409 — cashbox_kkm_unknown у GET /cashbox/shifts и POST /cashbox/shifts/close, rfo_missing у GET /cashbox/summary и обоих тумблеров. Если ОФД у клиента нет — ждать нечего, номер кассы сам не появится.

Если клиент утверждает, что Kaspi Касса у него есть, а ручки всё равно отдают 409: при нескольких кассах передайте kaspi_connection_id нужной точки, а состояние организации пересверяется в кабинете — Настройки → вкладка «Организация» → карточка «Информация об организации» → кнопка «Обновить информацию» (доступна только владельцу организации, не чаще раза в 5 минут) — либо переподключением кассира. Предупредите клиента: то же действие включает каталог товаров, и после него POST /invoices/qr и POST /static-qr без cart_items начнут отвечать 422 catalog_requires_cart_items, а уже напечатанные QR-листы без состава перестанут работать — переиздать их нельзя.

В песочнице касса отвечает всегда — детерминированными данными, независимо от того, подключена ли она в бою и есть ли кассир. Интеграцию, прошедшую в песочнице, обязательно прогоните на боевой организации клиента, иначе первые 409 вы увидите уже в проде. Раздел «Касса» в кабинете тестовой организации при этом появляется, только если организация создана с ответом «касса есть» (ответ меняется в настройках).

Порядок вызовов

1. GET /cashbox/summary?date=YYYY-MM-DD — наличные за день: остаток в кассе, внесено, изъято, продажи и возвраты наличными. Суммы приходят строками «N.NN» и могут быть null — это «Kaspi не отдал поле», а не ноль. Оплаты по счетам ApiPay сюда не попадают.
2. GET /cashbox/shifts?date_from=&date_to= — список смен. Обе границы обязательны, окно не длиннее 31 дня, иначе 422. Запрос идёт в кассу Kaspi и отвечает не мгновенно. Этот вызов обязателен перед сверкой: он сохраняет смены на нашей стороне.
3. GET /cashbox/shifts/{id}/report — отчёт по смене. Возвращает не файл, а подписанную ссылку со сроком жизни около 15 минут: скачивай сразу, ссылку не храни и не логируй — она открывается без ключа.
4. GET /cashbox/reconciliation?shift_id={id} — сверка: рядом ваши оплаченные счета (ours, окно по дате оплаты) и итог кассы (kaspi) плюс discrepancies с причинами расхождения. Без шага 2 придёт 404 cashbox_shift_not_found.

Закрытие смены — асинхронное

POST /cashbox/shifts/close с телом {"client_operation_id": "…", "shift_number": 106} отвечает 202. Результат читай поллингом GET /cashbox/operations/{id} либо вебхуками cashbox.shift_closed / cashbox.shift_close_failed (дедуплицируй по паре event + operation.id).

• client_operation_id уникален на организацию: повтор тем же ключом → 409 cashbox_duplicate_operation с id уже идущей операции.
• resolution.safe_to_retry равен true только при статусе failed. Отказ не гарантирует, что смена осталась открытой: если ответ Kaspi не дошёл, она могла закрыться. Повтор безопасен — уже закрытая смена считается успехом.
• Повтор всегда с новым client_operation_id: прежний после отказа не освобождается.

Тумблеры автозакрытия и автоизъятия

PUT /cashbox/settings/auto-close и PUT /cashbox/settings/auto-withdrawal с телом {"enabled": true} отвечают {"changed":…, "new_value":…}. Запрос идемпотентен по живому значению на кассе: changed:false — не ошибка, там уже стояло запрошенное значение. 503 cashbox_toggle_in_progress — настройку меняет другой запрос; 503 cashbox_toggle_unavailable — изменение не применено.

GET /cashbox/settings отдаёт сохранённые значения и может вернуть null — это «сохранённого значения ещё нет», а не «выключено». Живое состояние приходит в других ответах: автозакрытие — в GET /cashbox/shifts, автоизъятие — в GET /cashbox/summary.

Подробнее — автозакрытие смены, отчёт по смене, сверка кассы со счетами.