Kaspi Pay — главный платёжный шлюз для приложений в Казахстане. Подключение занимает 2–4 недели и требует следующих шагов.
Основная часть срока — это не программирование, а документы и согласования. Сама интеграция API занимает несколько дней; всё остальное время уходит на регистрацию мерчанта, получение боевых кредов и настройку фискализации. Поэтому подключение платежей запускают параллельно с разработкой, а не после неё.
Шаг 1: Регистрация мерчанта
Заявка на kaspi.kz/business, документы юридического лица, подписание договора. Срок: 7–14 дней.
Подготовьте заранее: свидетельство о регистрации ИП или ТОО, БИН/ИИН, банковские реквизиты, описание вида деятельности и ссылку на работающий сайт или приложение. Проверяющие смотрят на реальность бизнеса: у сайта должны быть публичная оферта, условия доставки и возврата, контакты и реквизиты. Отсутствие этих страниц — самая частая причина возврата заявки.
Отдельно уточните категорию товаров. Часть категорий регулируется и требует сертификатов или лицензий; выяснить это лучше на старте, а не после того, как приложение готово.
Шаг 2: Тестовый аккаунт
Получение sandbox-кредов, тестовая карта, тестовые суммы. Все интеграции тестируем здесь.
В песочнице обязательно прогоняют не только успешную оплату, но и все ветки, которые встретятся в бою: отказ банка, недостаток средств, закрытие браузера на середине оплаты, дубль платежа, частичный и полный возврат. Сценарий «пользователь оплатил, но не вернулся в приложение» — самый частый источник расхождений в отчётности.
Держите тестовые и боевые ключи в разных конфигурациях окружения и никогда не храните их в репозитории. Смена ключей при переходе в прод должна быть заменой переменных окружения, а не правкой кода.
Шаг 3: Интеграция API
Kaspi Pay API REST + webhooks для уведомлений о статусах оплаты. Используем PHP/Node.js/Go SDK.
Три правила, которые экономят недели отладки. Первое: источник истины о статусе платежа — вебхук и запрос статуса на сервере, а не то, что вернулось в приложение. Клиентское устройство может потерять сеть в любой момент. Второе: каждый заказ получает собственный идентификатор, и повторный вебхук с тем же идентификатором не должен создавать второй заказ — обработчик обязан быть идемпотентным. Третье: логируйте все входящие уведомления целиком, иначе разбор спорной оплаты через месяц превращается в гадание.
Не забудьте про таймауты и повторы. Если ваш сервер ответил на вебхук ошибкой или отвечал слишком долго, уведомление придёт снова. Обработчик должен отвечать быстро, а тяжёлую работу — списание остатков, отправку чека, уведомление — выносить в очередь.
Шаг 4: Фискализация
Каждая оплата требует чека через ИС ЭСФ. Подключение касс через сервисы типа TCC, Sapa Avto, Kassa.kz.
Фискализация — отдельная интеграция со своей логикой, и её часто недооценивают. Чек должен уходить автоматически после подтверждения оплаты, а не по нажатию менеджера. Продумайте очередь и повторные попытки: если касса недоступна, чек нужно поставить в очередь и отправить позже, сохранив связь с заказом.
Отдельно опишите поведение при возврате: возврат денег и фискальный возврат — два разных действия, и они должны выполняться согласованно. Расхождение между ними всплывает при сверке и стоит бухгалтерии много времени.
Шаг 5: Production-запуск
Кредитные карты Visa/Mastercard, рассрочка, БНПЛ, Kaspi Bank переводы. Включаем поэтапно.
Поэтапно — значит: сначала обычная оплата картой на небольших суммах, затем рассрочка и BNPL. Рассрочка меняет пользовательский сценарий: сумма и срок влияют на доступность метода, а часть заказов уходит в отдельный процесс подтверждения. Это нужно отразить и в интерфейсе, и в статусах заказа.
Перед боевым запуском проведите контрольную оплату реальной картой на минимальную сумму, дождитесь чека, сделайте возврат и убедитесь, что деньги и фискальный документ вернулись корректно. Только после этого включайте оплату всем пользователям.
Сверка и отчётность
После запуска появляется задача, о которой на этапе разработки не думают: ежедневная сверка. Нужно сопоставлять три набора данных — заказы в вашей системе, транзакции шлюза и фискальные чеки. Расхождения возникают всегда: отменённые платежи, задвоенные вебхуки, возвраты, оформленные вручную.
Практично сразу сделать простую служебную страницу, где оператор видит заказ, статус платежа, номер транзакции и статус чека в одной строке. Без неё каждый спорный случай превращается в задачу для разработчика и запрос логов, а это дни ожидания вместо минуты.
Типичные ошибки
- Считать заказ оплаченным по ответу мобильного клиента, без подтверждения на сервере.
- Не обрабатывать повторные вебхуки — в результате дубли заказов и двойные списания остатков.
- Отправлять чек вручную. При любом всплеске заказов это перестаёт работать.
- Не логировать сырые уведомления шлюза — разбор спора становится невозможным.
- Хранить боевые ключи в коде и в репозитории.
- Забыть про возвраты: сценарий возврата почти всегда всплывает в первую неделю после запуска.
Что спросить у подрядчика
- Где хранятся ключи и как они меняются при переходе с песочницы на прод?
- Идемпотентен ли обработчик вебхуков и как он ведёт себя при повторной доставке?
- Что происходит, если касса недоступна в момент оплаты?
- Как реализован возврат — деньги и фискальный чек одновременно?
- Есть ли отдельная страница со статусами платежей для оператора, чтобы разбираться без разработчика?
Стоимость в ZoomApps
Подключение Kaspi Pay в существующее приложение — от 280 000 ₸ за работы и 5 рабочих дней.
Если приложения ещё нет, платежи закладывают сразу в проект: разработка мобильного приложения начинается от 850 000 ₸, а оценка по типам продуктов разобрана в материале о том, сколько стоит мобильное приложение. Для интернет-магазина оплата и фискализация входят в базовый объём работ — разработка интернет-магазина от 950 000 ₸.
Практический вывод: начинайте с документов, а не с кода. Пока идёт регистрация мерчанта, реализуйте серверную часть на песочнице и сразу закладывайте идемпотентность вебхуков, очередь чеков и сценарий возврата. Тогда переход в бой сведётся к замене ключей и одной контрольной оплате.