WordPress / WooCommerce: приём оплаты через Kaspi (плагин Qut Pay)

Плагин добавляет в магазин WooCommerce способ «Оплатить через Kaspi»: покупатель выбирает Kaspi на кассе → переходит на страницу оплаты Qut Pay (QR, на телефоне — оплата в Kaspi в одно нажатие) → в момент оплаты заказ автоматически переходит в «Обработка/Выполнен», чек уходит покупателю, вам приходит уведомление в Telegram. Деньги поступают напрямую на ваш счёт Kaspi Pay.

Требования: WordPress 6.0+, WooCommerce 7.0+ (подходят и классическая касса, и Checkout Blocks, и HPOS), PHP 7.4+, сайт открывается по https, валюта магазина — KZT (₸). Организация в кабинете Qut Pay с подключённым кассиром Kaspi (для проверки в sandbox кассир не нужен).

Время: 10–15 минут.

Шаг 1. Установка плагина

WordPress → Плагины → Добавить новый → в поиске введите Qut Pay → «Qut Pay for WooCommerce» → Установить → Активировать. Плагин опубликован в официальном каталоге WordPress.org: https://wordpress.org/plugins/qut-pay-for-woocommerce/
Или архивом: https://api.qut.kz/downloads/qutpay-for-woocommerce.zip → Плагины → Добавить новый → Загрузить плагин → zip → Установить → Активировать.
Если в списке плагинов есть старая/повреждённая запись «qutpay-for-woocommerce» (например, «Файл плагина не найден»), сначала удалите её, при необходимости удалите на хостинге папку wp-content/plugins/qutpay-for-woocommerce, затем загрузите заново.

Шаг 2. Ключ и webhook в кабинете Qut Pay

Кабинет: https://qut.kz/app/ (вход — номер + код).

Интеграции → API-ключи: название — ваш сайт (например qazaqtoday.info) → Создать. Ключ показывается один раз, скопируйте его. В sandbox-организации выдаётся qp_test_…, в live — qp_live_….
Интеграции → Webhook: в поле адреса `` https://ВАШ_САЙТ/wp-json/qutpay/v1/webhook ` В списке «Ключ» выберите только что созданный ключ (тогда будут приходить только счета этого сайта) → Создать. Скопируйте показанный секрет (whsec_…), он тоже показывается один раз. Если на сайте отключены «Постоянные ссылки», адрес: https://ВАШ_САЙТ/?rest_route=/qutpay/v1/webhook`.

Шаг 3. Настройка WooCommerce

WooCommerce → Настройки → Платежи → «Qut Pay (Kaspi QR)» → Управление:

Поле	Что указать
Включить	✔
Название на кассе	название, которое видит покупатель; можно оставить по умолчанию
Описание	короткое пояснение на кассе
API-ключ	ключ из шага 2
Секрет webhook	`whsec_…` из шага 2
Адрес API	`https://api.qut.kz` — не меняйте
Статус после оплаты	физический товар — Обработка (processing), цифровая услуга/курс — Выполнен (completed)
Лог	на время проверки ✔ (WooCommerce → Статус → Логи → `qutpay`)

Сохранить изменения. Проверьте, что WooCommerce → Настройки → Общие → Валюта = Казахстанский тенге (KZT), иначе способ не появится на кассе.

Шаг 4. Проверка

Sandbox (без реальных денег): пока организация в кабинете находится в режиме sandbox, счета не уходят в Kaspi. Оформите заказ в магазине, выберите способ Kaspi → на странице оплаты Qut Pay нажмите кнопку «[Sandbox] имитировать оплату» → вы вернётесь на сайт, заказ станет «Обработка/Выполнен», в заметках заказа появится «Qut Pay: оплачен, счёт inv_…».

Live (реальные платежи): в кабинете Kaspi → Добавить кассира (по SMS-коду), затем переключите режим на Live, создайте live-ключ (qp_live_…) и укажите его в плагине. Создайте тестовый товар за 10 ₸ и оплатите его с собственного телефона: в течение 3 секунд заказ станет оплаченным, ссылка на чек появится на странице «Спасибо», вам придёт уведомление в Telegram. Затем сделайте возврат заказа из кабинета (Счета → … → Возврат) и убедитесь, что в WooCommerce он стал «Возвращён».

Как это работает

При оформлении заказа плагин вызывает POST /api/v1/invoices (externalOrderId = номер заказа, Idempotency-Key = wc-{id}-…, поэтому при двойном нажатии не появится два счёта) и перенаправляет покупателя на payUrl.
Счёт находится в состоянии pending 3 минуты (срок действия Kaspi QR). Если не оплачен — expired → заказ «Отменён»; если позже придёт запоздавшая оплата, webhook invoice.paid снова сделает заказ «Оплачен».
У каждого события webhook проверяются X-Webhook-Signature (HMAC-SHA256) и X-Webhook-Timestamp, неверная подпись → 401. Если одно событие пришло дважды, заказ не изменится дважды.
На странице «Спасибо» плагин повторно запрашивает статус у API (даже если webhook задержится, заказ отобразится корректно).
Возврат: в карточке заказа «Возврат» → плагин вызывает POST /invoices/{id}/refund (у ключа должно быть право refunds:write — при создании ключа поставьте отметку «разрешить возвраты»).

Частые проблемы

Признак	Причина / решение
Способ Kaspi не виден на кассе	Валюта не KZT; плагин не включён; ключ пустой
«Файл плагина не найден»	Старый архив (собранный в Windows). Удалите папку плагина и загрузите новый zip
Заказ остаётся в состоянии «Ожидает оплаты»	Webhook не зарегистрирован в кабинете или секрет не совпадает. Кабинет → Интеграции → Webhook → «Журнал доставки»: 401 — неверный секрет, 404 — неверный адрес (`/wp-json/qutpay/v1/webhook`), 5xx — ошибка сайта (Логи → qutpay)
В журнале webhook «timeout»	Сайт отвечает дольше 8 секунд (плагин кэширования/защита). Если есть Cloudflare, поставьте путь `/wp-json/qutpay/` в «Bypass»
`kaspi_session_expired`	В кабинете прервана сессия кассира: Kaspi → кассир → повторный вход по SMS-коду
`tariff_limit_reached`	Исчерпан дневной лимит: продление на странице Тариф
В live счёт не создаётся, в sandbox создаётся	В плагине стоит sandbox-ключ (`qp_test_`) — укажите live-ключ

Вопросы: https://t.me/qutpaybot или kazprose@gmail.com. Полное описание API: https://api.qut.kz/docs

Нужна помощь? WhatsApp +77788813333 · kazprose@gmail.com · 09:00–21:00 (Алматы)
Можно написать и из кабинета: Поддержка.

Qut Pay — независимый сервис, не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки правообладателя.