Kaspi POS Automation

Автоматизация платежей для POS-систем через Kaspi Pay API. Проект предоставляет серверное приложение и веб-интерфейс для создания счетов, генерации QR-кодов, просмотра истории транзакций и оформления возвратов.

Архитектура

┌──────────────┐       ┌──────────────────┐       ┌──────────────────┐
│  Web UI      │◄─────►│  Express Server   │◄─────►│  Kaspi Pay API   │
│  (public/)   │       │  (server.js)      │       │  (entrance/      │
│              │       │                   │       │   mtoken/qrpay)  │
└──────────────┘       └──────────────────┘       └──────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │   src/            │
                    │  ├─ config.js     │  Keypair, device, constants
                    │  ├─ crypto.js     │  ECDH, ECDSA, TOTP, AES
                    │  ├─ helpers.js    │  Fetch wrapper, headers
                    │  ├─ session.js    │  Stateless session factory
                    │  ├─ logger.js     │  File & console logging
                    │  ├─ polling.js    │  Payment status polling
                    │  ├─ webhookStore  │  Webhook management
                    │  └─ routes/       │  API route handlers
                    │     ├─ auth.js    │  SMS auth (3-step)
                    │     ├─ invoice.js │  Invoice creation
                    │     ├─ qr.js      │  QR code generation
                    │     ├─ history.js │  Transaction history
                    │     ├─ refund.js  │  Refund processing
                    │     └─ session.js │  Session management
                    └───────────────────┘

Сервер stateless после авторизации — данные сессии (зашифрованный vtokenSecret, tokenSN, profileId) хранятся на стороне клиента и передаются через заголовки.

Webhooks

Сервер автоматически отслеживает статусы созданных QR- и invoice-платежей (polling каждые 3 сек.) и отправляет HTTP POST-уведомления на указанные URL при изменении статуса.

• 📡 События: payment.success · payment.failed · payment.expired
• ⚙️ Настройка: файл webhooks.json (см. webhooks.example.json)
• 🔐 Подпись: HMAC SHA-256
• 🔄 Retry: до 3 попыток с нарастающей задержкой

📖 Подробнее — в документации API.

Требования

• Node.js ≥ 20.6

Быстрый старт

# 1. Клонировать репозиторий
git clone https://github.com/tapter-dev/kaspi-pos-automation.git
cd kaspi-pos-automation

# 2. Установить зависимости
npm install

# 3. Создать .env с ключом шифрования
echo "TOKEN_SECRET_KEY=$(openssl rand -hex 32)" > .env

# 4. (Опционально) Настроить вебхуки
cp webhooks.example.json webhooks.json
# Отредактируйте webhooks.json под свои нужды

# 5. Запустить сервер
npm start

При первом запуске автоматически генерируются keypair.json и device.json.

Переменные окружения

Переменная	Описание	По умолчанию	Обязательная
TOKEN_SECRET_KEY	64-символьная hex-строка для AES-256-GCM	—	Да
PORT	Порт сервера	3000	Нет
APP_VERSION	Версия приложения Kaspi Pay	4.110.1	Нет
APP_BUILD	Номер сборки	1099	Нет
APP_PLATFORM	Платформа устройства	iOS	Нет
APP_PLATFORM_VER	Версия ОС	18.5	Нет
APP_LOCALE	Локаль	ru-RU	Нет
APP_MODEL	Модель устройства	iPhone17,3	Нет
APP_BRAND	Бренд устройства	Apple	Нет
APP_DEVICE_NAME	Имя устройства	iPhone	Нет
APP_SCREEN_W	Ширина экрана	393.0	Нет
APP_SCREEN_H	Высота экрана	852.0	Нет
APP_CFNETWORK	Версия CFNetwork	CFNetwork/3826.500.131	Нет
APP_DARWIN	Версия Darwin	Darwin/24.5.0	Нет

⚠️ Параметры APP_* соответствуют реальному клиенту Kaspi Pay. API Kaspi валидирует эти значения и может отклонить запросы с неизвестными параметрами. Обновляйте их при выходе новой версии приложения.

Ротация ключей

npm run regen:keypair   # Перегенерация ECDSA-ключей
npm run regen:device    # Перегенерация идентификатора устройства

Старые файлы сохраняются как .bak. После ротации существующие сессии становятся недействительными.

Демо-интерфейс (public/)

В папке public/ находится встроенный веб-интерфейс (SPA), который запускается автоматически вместе с сервером и доступен по адресу http://localhost:3000.

Возможности интерфейса:

• 🔐 Авторизация — вход по номеру телефона кассира Kaspi Pay через 3-шаговый SMS-flow (ввод номера → OTP-код → завершение)
• 🧾 Выставление счёта — создание счёта по номеру телефона клиента с указанием суммы и комментария
• 📱 QR-оплата — генерация QR-кода для оплаты с отслеживанием статуса в реальном времени
• 📋 История операций — просмотр списка транзакций с детализацией
• 💰 Продажи и возвраты — статистика продаж и оформление возвратов

Файлы:

Файл	Описание
public/index.html	HTML-разметка и стили интерфейса
public/app.js	Клиентская логика (API-вызовы, управление состоянием)

Интерфейс предназначен для демонстрации и тестирования API. Для продакшена рекомендуется использовать собственный фронтенд.

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

Подробная документация по всем эндпоинтам API: docs/API.md.

📗 Документация также доступна на казахском языке: README.kk.md | docs/API.kk.md

Разработка

# Линтинг
npm run lint

# Форматирование
npm run format

# Тесты
npm test

Лицензия

Этот проект распространяется под лицензией MIT.

Участие в проекте

Мы приветствуем вклад сообщества! Пожалуйста, ознакомьтесь с CONTRIBUTING.md перед созданием pull request.