Қысқаша
Плагин WooCommerce кассасына «Kaspi арқылы төлеу» әдісін қосады: сатып алушы Kaspi-ді таңдайды → Qut Pay төлем бетіне өтеді (QR немесе Kaspi сілтемесі) → төлеген сәтте тапсырыс автоматты түрде «Обработка» немесе «Выполнен» болады. Ақша тікелей сіздің Kaspi Pay шотыңызға түседі.
Жүктеу: https://api.qut.kz/downloads/qutpay-for-woocommerce.zip Толық нұсқаулық: https://api.qut.kz/docs/guide/wordpress
Барлығы 10-15 минут алады.
Талаптар
| Не | Мәні |
|---|---|
| WordPress | 6.0 және жоғары |
| WooCommerce | 7.0 және жоғары. Классикалық касса, Checkout Blocks және HPOS қолдау көрсетіледі |
| PHP | 7.4 және жоғары |
| Сайт | https арқылы ашылуы керек |
| Дүкен валютасы | KZT (₸). Басқа валютада әдіс кассада мүлде көрінбейді |
| Qut Pay | Kaspi кассирі қосылған ұйым. Sandbox-та сынау үшін кассир керек емес |
1-қадам. Плагинді орнату
- Архивті жүктеп алыңыз.
- WordPress → Плагины → Добавить новый → Загрузить плагин → zip файлын таңдаңыз → Установить → Активировать.
- Егер тізімде ескі немесе бұзылған «qutpay-for-woocommerce» жазбасы тұрса, алдымен оны жойыңыз, керек болса хостингтегі
wp-content/plugins/qutpay-for-woocommerceқалтасын өшіріңіз, сосын қайта жүктеңіз.
2-қадам. Кілт пен webhook
Кабинет: https://qut.kz/app
- Интеграциялар → API кілттері → атауы ретінде сайтыңызды жазып, Жасау. Кілт бір рет қана көрсетіледі — бірден көшіріп алыңыз. Қайтару жасай алу үшін кілтке
refunds:writeрұқсатын қосыңыз. - Интеграциялар → Webhook → адрес:
`` https://САЙТЫҢЫЗ/wp-json/qutpay/v1/webhook ``
«Кілт» тізімінен жаңа ғана жасаған кілтті таңдаңыз — сонда бұл адреске тек осы сайттың оқиғалары келеді. Жасау → көрсетілген құпияны (whsec_…) көшіріп алыңыз, ол да бір рет көрсетіледі.
Сайтта «Постоянные ссылки» өшірулі болса, адрес басқаша болады: https://САЙТЫҢЫЗ/?rest_route=/qutpay/v1/webhook.
3-қадам. Баптау
WooCommerce → Настройки → Платежи → «Qut Pay (Kaspi QR)» → Управление:
| Өріс | Не қою керек |
|---|---|
| Включить | ✔ |
| Название на кассе | Сатып алушы көретін атау. Әдепкісін қалдыруға болады |
| Описание | Кассадағы қысқа түсінік |
| API-ключ | 2-қадамдағы кілт |
| Секрет webhook | 2-қадамдағы whsec_… |
| Адрес API | https://api.qut.kz — өзгертпеңіз |
| Статус после оплаты | Физикалық тауар — Обработка (processing), цифрлық қызмет немесе курс — Выполнен (completed) |
| Лог | Сынау кезінде ✔ қойыңыз |
Сохранить изменения басыңыз. Сосын WooCommerce → Настройки → Общие → Валюта өрісінде Казахстанский тенге (KZT) тұрғанын тексеріңіз.
Тапсырыс күйі қалай ауысады
- Сатып алушы тапсырысты растағанда плагин
POST /api/v1/invoicesшақырады:externalOrderId— тапсырыс нөмірі,Idempotency-Key—wc-{id}-…. Сондықтан батырманы екі рет бассаңыз да екі счёт шықпайды. Сатып алушыpayUrlбетіне бағытталады. - Счёт
pendingкүйінде шамамен 3 минут тұрады — бұл Kaspi-дің QR сканерлеу терезесі. - Төленсе — webhook
invoice.paidкеледі, тапсырыс сіз таңдаған күйге ауысады, тапсырыс ескертпелерінде «Qut Pay: оплачен, счёт inv_…» жазылады. - Төленбесе — счёт
expiredболады, тапсырыс «Отменён» күйіне көшеді. - Кеш төлем. Счёт жабылғаннан кейін ақша келсе,
invoice.paidкейін де келеді және тапсырысты қайта «оплачен» етеді. Бұл қалыпты жағдай: не тауарды беріңіз, не ақшаны қайтарыңыз.
«Спасибо» бетінде плагин күйді API-дан қайта сұрайды — webhook кешіксе де сатып алушы дұрыс күйді көреді. Бір оқиға екі рет келсе, тапсырыс екі рет өзгермейді.
Қайтару
Қайтаруды WooCommerce-тің өз тапсырыс карточкасынан жасайсыз: тапсырысты ашып, «Возврат» батырмасын басыңыз. Плагин POST /invoices/{id}/refund шақырады. Ішінара қайтару да жұмыс істейді.
Шарты біреу: кілтте refunds:write рұқсаты болуы керек. Кілт жасағанда оны белгілемесеңіз, қайтару 403 қатесімен өтпейді — жаңа кілт жасап, плагиндегі мәнді ауыстырыңыз.
Қайтаруды кабинеттен де жасауға болады — ол кезде тапсырыс webhook арқылы жаңарады.
Чек
Төленген соң чек сілтемесі «Спасибо» бетінде шығады және тапсырыс ескертпесіне жазылады. Счёт жасағанда сатып алушының email-і берілсе, чек хаты да кетеді (кабинетте SMTP бапталған болса). Толығырақ: Чектер.
Сынау
Sandbox. Кабинетте ұйым sandbox режимінде тұрғанда счёттар Kaspi-ге кетпейді. Дүкенде тапсырыс жасап, Kaspi әдісін таңдаңыз → төлем бетіндегі «[Sandbox] төлемді имитациялау» батырмасын басыңыз → сайтқа қайтасыз, тапсырыс төленген күйге ауысады. Webhook-тар бұл кезде шынайы жіберіледі.
Live. Кассирді қосып, режимді live-қа ауыстырыңыз, qp_live_… кілт жасап плагинге қойыңыз. 10 ₸-ға тест тауар жасап, өз телефоныңызбен төлеңіз. Сосын сол тапсырысты қайтарып көріңіз — WooCommerce-те «Возвращён» болғанын тексеріңіз.
Жиі кездесетін мәселелер
| Белгісі | Себебі және шешімі |
|---|---|
| Кассада Kaspi әдісі көрінбейді | Валюта KZT емес; плагин қосылмаған; API кілт өрісі бос |
| «Файл плагина не найден» | Ескі немесе бұзылған архив. Плагин қалтасын өшіріп, жаңа zip-ті жүктеңіз |
| Тапсырыс «Ожидает оплаты» күйінде қалып қояды | Webhook тіркелмеген немесе құпия сәйкес емес. Кабинет → Интеграциялар → Webhook → Жеткізу журналы: 401 — құпия қате, 404 — адрес қате, 5xx — сайт қатесі |
| Журналда «timeout» | Сайт 8 секундтан ұзақ жауап береді. Кэш немесе қорғаныс плагинін тексеріңіз; Cloudflare болса /wp-json/qutpay/ жолын «Bypass» етіңіз |
kaspi_session_expired | Кассир сессиясы үзілген: кабинет → Kaspi → SMS кодпен қайта байланыстырыңыз |
tariff_limit_reached | Лимит толды: кабинет → Тариф |
| Live-та счёт жасалмайды, sandbox-та жасалады | Плагинде qp_test_… кілті тұр. Live кілт қойыңыз |
| Қайтару өтпейді | Кілтте refunds:write жоқ. Жаңа кілт жасаңыз |
Егер тізімдегі тексерулер көмектеспесе: Плагин істемей жатыр.
Жиі қойылатын сұрақтар
Checkout Blocks-пен жұмыс істей ме? Иә. Классикалық касса да, Blocks та, HPOS та қолдау көрсетіледі.
Сайтым http арқылы ашылады. Live режимде webhook адресі міндетті түрде https болуы керек. Сертификат орнатыңыз — қазір ол тегін.
Бірнеше дүкенім бар, бір кілт жетеді ме? Әр сайтқа бөлек кілт жасап, webhook адресін сол кілтке байлаған дұрыс: сонда әр дүкен тек өз оқиғаларын алады.
Сатып алушы төлем бетінен қайтып кетсе не болады? Тапсырыс «Ожидает оплаты» күйінде қалады, счёт өз мерзімінде expired болады. Сатып алушы тапсырысты қайта ашып, төлей алады.
Тапсырыс күйін өзім ауыстырсам, плагин оны қайта өзгерте ме? Менеджер тапсырысты processing немесе complete күйіне қойған болса, кешіккен expired/cancelled оқиғасы оны қайта өзгертпейді.
OpenCart дүкені үшін не істеу керек? Ол үшін бөлек кеңейту бар: OpenCart 4 кеңейтуі.