ДОКУМЕНТАЦИЯ KZ PAY
Документация KZ Pay
Установка плагина, активация лицензии, API-ключ Kaspi Pay, торговая точка и проверка оплаты в WooCommerce.
Требования перед установкой
- WordPress и активный WooCommerce, HTTPS на рабочем сайте, валюта KZT.
- Доступ продавца Kaspi Pay, API-ключ для своей организации и настроенная торговая точка.
- Поддерживаемая серверная среда с исходящим HTTPS, поддержкой GD/PNG и работающими задачами WordPress/WooCommerce.
- Лицензия или пробный период KZ Pay и доступ администратора WordPress.
KZ Pay не предоставляет доступ продавца, API-ключ или одобрение Kaspi Pay. Перед изменениями сделайте резервную копию сайта.
Загрузка и установка
- Оформите пробный период или покупку на странице KZ Pay.
- Загрузите ZIP через доступ, предоставленный Freemius после оформления. Для существующей покупки используйте письмо или кабинет клиента.
- В WordPress откройте Плагины → Добавить плагин → Загрузить плагин.
- Выберите ZIP, установите и активируйте KZ Pay.
- Убедитесь, что WooCommerce активен и плагин доступен в настройках платежей.
Не используйте ZIP из неизвестных источников. Если при обновлении WordPress предлагает заменить существующий плагин, убедитесь, что устанавливается нужный продукт и сохранена резервная копия.
Активация лицензии или пробного периода
После активации следуйте приглашению Freemius в WordPress. Используйте email покупки или предоставленный лицензионный ключ. Убедитесь, что аккаунт показывает действующую лицензию или активный пробный период.
Загрузка, обновления, доступ, управляемый лицензией, и поддержка зависят от состояния подписки и лицензии Freemius. При ошибке активации проверьте email, ключ, статус подписки и доступ сервера к Freemius. Не публикуйте лицензионный ключ.
Подключение Kaspi Pay
Откройте меню Kaspi Pay в админке либо WooCommerce → Настройки → Платежи → KZ Pay for WooCommerce. Названия ниже соответствуют англоязычным элементам интерфейса.
- В блоке Kaspi QR Connection укажите API-ключ своей организации.
- Нажмите Save API key. Сохраненный ключ шифруется и повторно не выводится.
- Нажмите Test connection и убедитесь, что проверка успешна.
- Нажмите Load trade points для получения доступных торговых точек.
- Выберите нужную точку в Trade point.
- Нажмите Register this store и дождитесь подтверждения Registered with Kaspi Pay.
Не отправляйте API-ключ Kaspi Pay, пароли и учетные данные в поддержку, на скриншоты или в публичные логи.
Торговая точка и регистрация магазина
Торговая точка определяет, куда относится оплата этого магазина. При регистрации KZ Pay связывает текущую установку WordPress и автоматически созданный KZ Pay Device ID с выбранной точкой.
Disconnect this store используется для отключения регистрации или переноса; после отключения прием платежей выключается. Не нажимайте его для обычной проверки соединения.
При переносе на другую установку WordPress проверьте новый Device ID и повторно зарегистрируйте магазин с правильной торговой точкой. Убедитесь, что рабочий сайт сохраняет необходимую лицензию.
Настройка оформления заказа
- API-ключ сохранен и соединение проверено.
- Торговая точка выбрана, магазин зарегистрирован.
- Включено Enable KZ Pay at WooCommerce checkout, настройки сохранены.
- Валюта оформления заказа и заказа WooCommerce: KZT.
Проверьте способ оплаты в вашей теме, классическом checkout или Checkout Blocks. Отсутствие метода нельзя исправить одним изменением его названия: нужно выполнить все условия готовности.
QR-код, мобильная ссылка и итоговый результат
После создания заказа KZ Pay открывает защищенную страницу оплаты и создает QR или платежную ссылку. С компьютера клиент сканирует QR телефоном. На телефоне он может перейти к оплате по ссылке на том же устройстве.
Создание QR и открытие ссылки не означают получение денег. KZ Pay отслеживает статус с сервера WordPress и обновляет заказ после проверенного итогового результата с соответствующей суммой и данными транзакции.
При ожидании итоговый результат еще не получен. При ошибке, отмене или истечении срока платеж не считается успешным. Если результат нельзя безопасно обработать автоматически, проверьте заметки заказа: может требоваться ручная проверка.
Проверка перед приемом реальных платежей
Владелец магазина должен проверить разрешенный для своего аккаунта платежный сценарий: получение QR или ссылки, подтверждение платежа, получение окончательного результата и правильное обновление заказа. Проверку выполняйте контролируемо, с доступом к фактической истории Kaspi Pay.
- Правильный ключ, торговая точка, регистрация и валюта.
- Лицензия или пробный период действуют.
- WP-Cron и Action Scheduler выполняют задачи.
- Сумма и результат платежа относятся к правильному заказу.
- Истечение срока и ошибка не приводят к отметке об успешной оплате.
Возвраты
Автоматические возвраты через API в текущей интеграции Kaspi QR недоступны. Сначала выполните денежный возврат в приложении Kaspi Pay, затем отразите его в WooCommerce. Запись возврата в WooCommerce не равнозначна фактическому возврату денег.
Диагностика настройки и оплаты
Плагин не виден при оплате
Проверьте чек-лист Checkout Setup, KZT, сумму заказа и лицензию. Завершите настройку ключа, точки и регистрации, включите checkout и сохраните настройки.
Соединение или торговые точки не работают
Проверьте API-ключ своей организации и исходящий HTTPS сервера. Уточните доступ и торговые точки в Kaspi Pay. Повторите Test connection и Load trade points после исправления причины.
Магазин не зарегистрирован
Выберите правильную точку, проверьте принадлежность ключа организации и повторите Register this store. При отказе передайте поддержке безопасное сообщение или reference запроса, если он доступен.
QR не создается
Проверьте готовность checkout, KZT, сумму и GD/PNG на сервере. При ожидании покупателя предложите другой метод оплаты, пока выясняется причина.
Заказ завис в ожидании
Проверьте историю Kaspi Pay, заметки заказа, WP-Cron и Action Scheduler. Не отмечайте оплату успешной по одному только QR или возвращению клиента на сайт.
Оплата есть, заказ не обновился
Проверьте заметки о ручной проверке, несовпадении суммы или отсутствующих данных транзакции. Не создавайте повторный платеж. Передайте поддержке номер заказа и безопасное описание.
Мобильная ссылка не открывается или платеж истек
Проверьте доступность приложения и актуальность ссылки. Используйте обычный браузер. Повторный платеж допустим после проверки предыдущего результата и только когда KZ Pay разрешает повторную попытку.
Лицензия не активируется
Проверьте аккаунт Freemius, email покупки, лицензию и подписку. Используйте правильные данные и проверьте сетевой доступ. При необходимости обратитесь в поддержку с email покупки.
Технические сведения
Этот раздел предназначен для администраторов и разработчиков. Текущая интеграция использует Kaspi Public QR API Scheme 1. Настройка сертификатов для других схем в WordPress не предусмотрена.
API-ключ передается сервером. При регистрации Kaspi возвращает DeviceToken для последующих запросов. Проверка статуса выполняется сервером, а не подтверждением в браузере. Внутренние статусы могут включать QrTokenCreated, RemotePaymentCreated, Wait, Processing и Processed; итог нужно интерпретировать вместе с данными транзакции, а не только по названию статуса.
Текущая интеграция не предоставляет платежные webhooks, автоматические API-возвраты или интеграцию с маркетплейсом Kaspi Shop. Не подменяйте готовую настройку ручным редактированием токенов.
Помощь с KZ Pay
Пишите на support@group-starlight.com. Укажите версии WordPress, WooCommerce и KZ Pay, номер заказа и краткое описание. Скройте секретные значения на скриншотах и в выдержках логов.
Не отправляйте API-ключи, пароли, полные конфиденциальные логи или платежные данные покупателей. Вопросы лицензии и загрузки также доступны через кабинет клиента.
Подключите Kaspi QR к WooCommerce
Изучите требования и попробуйте KZ Pay в течение 7 дней без банковской карты.