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-қадам. Плагинді орнату

Архивті жүктеп алыңыз: https://api.qut.kz/downloads/qutpay-for-woocommerce.zip
WordPress → Плагины → Добавить новый → Загрузить плагин → zip → Установить → Активировать.
Егер плагиндер тізімінде ескі/бұзылған «qutpay-for-woocommerce» жазбасы болса (мысалы, «Файл плагина не найден»), алдымен оны жойыңыз, керек болса хостингтегі wp-content/plugins/qutpay-for-woocommerce қалтасын өшіріңіз, сосын қайта жүктеңіз.

2-қадам. Qut Pay кабинетінде кілт және webhook

Кабинет: 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	2-қадамдағы `whsec_…`
Адрес 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 — құқық иесінің тауар белгілері.