Документация
API.

Справочник по REST API kaspipos. Все запросы идут на ваш сервер kaspipos, отвечают JSON. Платёжные эндпоинты авторизуются заголовком X-Api-Key. Базовый URL в разработке — http://localhost:3000.

01 / Быстрый старт

Чтобы принять первый платёж, нужно: войти в кабинет через Google, подключить Kaspi Pay (телефон роли кассира + SMS-код) и создать API-ключ. Всё это делается один раз в веб-кабинете.

Шаг 1 — Подключить Kaspi и получить ключ

В кабинете подключите Kaspi Pay в разделе «Kaspi-касса», затем в разделе «API-ключи» нажмите «Создать ключ». Ключ показывается полностью один раз — сохраните его. Подробнее — в разделе «Кабинет и ключи».

Шаг 2 — Первый запрос

# Создать QR-платёж
curl -X POST http://localhost:3000/api/qr/create \
  -H "X-Api-Key: kpos_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500 }'

Шаг 3 — Получить вебхук

Когда клиент оплачивает QR, платёж отслеживается автоматически, и при финальном статусе на ваш endpoint приходит POST с событием payment.success и подписью в заголовке X-Webhook-Signature. Вебхуки настраиваются в кабинете.

02 / Авторизация

Платёжные эндпоинты (/api/qr, /api/invoice, /api/refund, /api/history, /api/session) принимают заголовок X-Api-Key с действующим ключом — либо cookie-сессию кабинета, если запрос идёт из браузера вошедшего мерчанта.

X-Api-Key:    kpos_7f2a8c... // ключ из кабинета
Content-Type: application/json

Эндпоинты кабинета (/api/account, /api/auth, /api/keys, /api/payments, /api/webhooks) авторизуются только cookie-сессией и предназначены для веб-кабинета.

03 / Ошибки

При ошибке ответ — JSON с одним полем error и соответствующим HTTP-кодом.

{ "error": "amount required" }

Ответ Kaspi может иметь HTTP 200, но содержать собственный StatusCode ≠ 0 и поле Message — проверяйте тело ответа, а не только HTTP-код.

04 / Создать QR-платёж

Создаёт QR-платёж и возвращает ссылку для оплаты. Платёж автоматически отслеживается; при финальном статусе уходит вебхук.

Пример запроса

curl -X POST http://localhost:3000/api/qr/create \
  -H "X-Api-Key: kpos_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500 }'

Пример ответа

{
  "StatusCode": 0,
  "Data": {
    "QrOperationId": 789012,
    "QrToken":      "https://pay.kaspi.kz/pay/...",
    "ExpireDate":   "2026-01-01T12:05:00",
    "Amount":       500
  }
}

05 / Статус QR

Возвращает текущий статус QR-платежа от Kaspi. Полезно для синхронной сверки — но в общем случае надёжнее доверять вебхуку.

Промежуточные статусы QR: QrTokenCreated, Wait. Финальные: Processed (успех), Expired / QrTokenDiscarded (просрочка), прочие — отказ.

06 / Счёт на телефон

Выставляет счёт на оплату прямо в приложение Kaspi клиента по номеру телефона. Как и QR, счёт отслеживается автоматически.

curl -X POST http://localhost:3000/api/invoice/create \
  -H "X-Api-Key: kpos_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "77001234567",
    "amount":      2500,
    "comment":     "Заказ ORDER-9821"
  }'

Ответ: { "StatusCode": 0, "Data": { "Id", "Status": "RemotePaymentCreated", "Amount", ... } }.

Детали счёта

Текущее состояние ранее выставленного счёта.

Отменить счёт

Отменяет неоплаченный счёт. Тело: { "operationId": "123456" }.

Клиент по номеру

Информация о клиенте Kaspi по номеру телефона.

История счетов

Последние 20 счетов. Тело запроса — пустой объект {}.

07 / Возврат

Полный или частичный возврат проведённого QR-платежа. Деньги уходят обратно клиенту в Kaspi.

08 / История операций

История операций напрямую из Kaspi.

Детали операции

Детали одной операции. Тело: id (number, обязательно) и operationMethod (number, опционально, по умолчанию 0).

09 / Проверка сессии

Живая проверка Kaspi-сессии — делает реальный запрос к Kaspi и сообщает, принят ли токен.

// сессия активна
{ "active": true }

// сессия отклонена Kaspi
{ "active": false, "error": "...", "code": 401 }

10 / Webhooks

Вебхук — это HTTP POST от kaspipos в ваше приложение при финальном статусе платежа. Endpoint-адреса, события и секрет подписи настраиваются в кабинете, раздел «Webhooks».

События

Тело вебхука

{
  "event":      "payment.success",
  "paymentId":  "789012",
  "type":       "qr",
  "status":     "Processed",
  "statusDesc": "",
  "amount":     500,
  "qrToken":    "https://pay.kaspi.kz/pay/...",
  "receiptUrl": "https://...",
  "orderNumber": "...",
  "data":       { },
  "timestamp":  "2026-01-01T12:00:00.000Z"
}

Подпись HMAC

Если для вебхука задан секрет, тело подписывается HMAC-SHA256 и подпись передаётся в заголовке X-Webhook-Signature в формате sha256=<hex>.

import crypto from 'crypto'

function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader),
  )
}

Ретраи

• Доставка считается успешной, если ваш сервер ответил в течение 10 секунд.
• При сетевой ошибке или таймауте доставка повторяется — всего до 3 попыток.
• Интервалы повторов: через 5 секунд, затем через 30 секунд.

11 / Кабинет и ключи

Регистрация, подключение Kaspi, API-ключи и вебхуки настраиваются в веб-кабинете — программного API для этого нет (эти эндпоинты работают только по cookie-сессии).