Как работает верификация чеков Kaspi
В отличие от классических платёжных шлюзов, Kaspi не предоставляет прямой API для мерчантов. Вместо этого используется фискальный API Республики Казахстан.
Процесс:
1. Клиент переводит деньги через Kaspi на ваш счёт
2. Kaspi формирует фискальный чек с уникальным номером
3. Клиент отправляет номер чека в бота
4. Бот проверяет чек через фискальный API
5. API возвращает: сумму, получателя, дату, статус
6. Бот сравнивает данные и выдаёт доступ
Важно: Фискальный API проверяет подлинность чека, а не факт перевода. Это значит, что нужно валидировать сумму и получателя вручную.
OCR и QR-сканирование PDF чеков
Многие пользователи отправляют не номер чека, а PDF-файл или скриншот.
Подход 1 — QR-код: PDF чеки Kaspi содержат QR-код с URL проверки. Извлекаем QR через библиотеку pyzbar или OpenCV, парсим URL и получаем данные чека.
Подход 2 — OCR: Для скриншотов используем Tesseract OCR. Извлекаем номер чека регулярным выражением из распознанного текста.
Подход 3 — Гибридный: Сначала ищем QR-код (быстро, точно). Если QR не найден — применяем OCR (медленнее, но покрывает скриншоты).
Практика: QR-подход работает в 95% случаев для PDF. OCR нужен для ~5% случаев, когда пользователь отправляет скриншот.
Обработка edge cases
В продакшене вы столкнётесь с десятками крайних случаев:
Дубли: Один чек отправляют дважды (или мошенники шарят чеки). Решение: храните хеш каждого проверенного чека в базе.
Частичная оплата: Клиент платит 5000 вместо 10000 тенге. Решение: накапливайте частичные платежи и активируйте при достижении полной суммы.
Чек другого получателя: Клиент отправляет чек оплаты другому мерчанту. Решение: всегда проверяйте поле получателя.
Таймаут API: Фискальный API может отвечать до 30 секунд. Решение: асинхронная проверка с уведомлением по результату.
Новый чек не в базе: Kaspi может задерживать фискализацию до 24 часов. Решение: retry с нарастающей задержкой.
Архитектура платёжного модуля
Разделите платёжную логику на независимые слои:
1. Приём чека (Handler): Валидация формата, нормализация номера, проверка дублей.
2. Верификация (Service): Запрос к фискальному API, парсинг ответа, проверка суммы и получателя.
3. Активация (Action): Обновление статуса пользователя, выдача доступа, отправка подтверждения.
4. Аналитика (Observer): Логирование события в систему аналитики, обновление P&L.
Паттерн: Используйте очередь задач (Celery/asyncio) для верификации. Это позволяет обрабатывать пики нагрузки и ретраить неудачные проверки.
Храните raw response от API — это ваша бухгалтерская документация.
Безопасность и комплаенс
Хранение данных: Номера чеков и суммы хранятся в зашифрованном виде. Никогда не логируйте полные данные получателя.
Rate limiting: Ограничьте количество проверок на одного пользователя (5-10 в час). Это защитит от brute-force перебора номеров чеков.
Мониторинг аномалий: Отслеживайте паттерны: множество неудачных проверок с одного аккаунта, одинаковые суммы от разных пользователей.
Фискальное соответствие: Если вы принимаете оплату за товары/услуги, вы обязаны выдавать фискальный чек. Используйте ОФД-операторов Казахстана.
Рекомендация: Ведите лог всех проверок с таймстампами. Это пригодится при спорах и для бухгалтерии.