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

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

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

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

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

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

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

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

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

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

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

1. Клиент регистрируется на apipay.kz (вход по номеру телефона через WhatsApp). Это обязательно для обоих способов — кассир привязывается к аккаунту ApiPay, без регистрации подключить организацию нельзя. Регистрировать нужно на личный номер владельца/руководителя — на него идут уведомления о счетах и ошибках; это не номер кассира.
2. Клиент берёт отдельный номер телефона (SIM), не привязанный к его личному Kaspi.
3. В приложении Kaspi Business: Профиль → Сотрудники → добавить сотрудника с ролью «Кассир» на этот номер. После добавления Kaspi пришлёт на номер кассира ссылку на скачивание приложения Kaspi Business — устанавливать ничего не нужно, это сообщение лишь означает, что сотрудник-кассир создан и готов.
4. Способ 1 (рекомендуемый): в личном кабинете ApiPay открывает Настройки → вкладка «Авторизация Kaspi», вводит номер кассира и код из SMS — занимает около 1 минуты.
5. Способ 2: пишет в поддержку ApiPay в WhatsApp +7 708 516 74 89 номер кассира и название организации — специалист подключит за 15–30 минут.
6. Подробная инструкция по обоим способам: apipay.kz/connect-cashier.

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

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

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

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

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

API-ключ

1. Настройки → вкладка «Подключение».
2. Кнопка «Создать новый ключ».
3. Ключ показывается один раз в окне — нажми «Копировать» и сохрани сразу.

Адрес для вебхука (куда слать уведомления об оплате)

1. Там же, на карточке созданного ключа — кнопка «Изменить».
2. Поле «Адрес для уведомлений» — впиши публичный HTTPS-адрес обработчика (например https://ваш-сайт.kz/webhooks/apipay).

Секрет вебхука (для проверки подписи)

1. На карточке ключа — кнопка «Создать подпись».
2. Секрет тоже показывается один раз — скопируй сразу.

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

APIPAY_API_KEY=...
APIPAY_WEBHOOK_SECRET=...
APIPAY_BASE_URL=https://bpapi.bazarbay.site/api/v1

Шаг 4. Встрой создание счёта

Создать счёт — POST /invoices

// выполняется на сервере
const res = await fetch('https://bpapi.bazarbay.site/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',       // необязательно, до 500 символов
    external_order_id: 'order_123'   // необязательно — ваш ID заказа для сверки
  })
})
const invoice = await res.json()
// → { id, amount, status: 'processing', phone, created_at }

Клиент получит уведомление в приложении Kaspi и оплатит там. Сохрани invoice.id рядом со своим заказом.

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

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

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

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

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

Другие события: invoice.refunded, subscription.payment_succeeded, subscription.payment_failed, subscription.grace_period_started, subscription.expired, webhook.test.

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

Каждый вебхук содержит заголовок 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')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

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

Если твой сервер не ответил 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. Опрос полезен и при наличии вебхука — как сверка, если все 11 попыток не прошли.

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

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

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

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

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

Полная таблица ошибок (QR-счета, возвраты) — в docs.html.

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

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

• status — стал error;
• error_message — причина текстом от Kaspi. Частое: номер клиента не зарегистрирован в Kaspi; Kaspi временно недоступен.

Ошибки Kaspi приходят сырым текстом, фиксированных кодов у них нет. «Номер не в Kaspi» — попроси клиента дать номер с установленным приложением Kaspi. «Временно недоступен» — повтори создание счёта позже.

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

Сессия кассира стабильна и обычно живёт месяцами — ежедневно или по расписанию переподключать кассу не нужно. Прерваться она может только при конкретных событиях: владелец вошёл в Kaspi с другого устройства или Kaspi сам сбросил сессию. В этом случае API отдаёт 503 kaspi_session_invalid. Ретраи запроса не помогут: владелец организации один раз переподключает кассу по SMS — кабинет, Настройки → «Авторизация Kaspi», либо через поддержку. Инструкция: /connect-cashier.

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

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

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

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

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

1. Кассир Kaspi подключён по /connect-cashier, подписка оплачена (после подключения — 3 дня бесплатно).
2. В кабинете, Настройки → «Подключение» — переключатель ТЕСТОВЫЙ → РАБОЧИЙ режим.
3. В рабочем режиме счета уходят в реальный Kaspi, клиенты платят настоящими деньгами.

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