# WooCommerce плагині

> Qut Pay плагинін WordPress дүкеніне орнату, API кілт пен webhook баптау, тапсырыс күйінің қалай ауысатыны, қайтару, чек және жиі кездесетін мәселелердің шешімі.

## Қысқаша

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

1. Архивті жүктеп алыңыз.
2. WordPress → **Плагины → Добавить новый → Загрузить плагин** → zip файлын таңдаңыз → **Установить** → **Активировать**.
3. Егер тізімде ескі немесе бұзылған «qutpay-for-woocommerce» жазбасы тұрса, алдымен оны жойыңыз, керек болса хостингтегі `wp-content/plugins/qutpay-for-woocommerce` қалтасын өшіріңіз, сосын қайта жүктеңіз.

## 2-қадам. Кілт пен webhook

Кабинет: https://qut.kz/app

1. **Интеграциялар → API кілттері** → атауы ретінде сайтыңызды жазып, **Жасау**. Кілт бір рет қана көрсетіледі — бірден көшіріп алыңыз. Қайтару жасай алу үшін кілтке `refunds:write` рұқсатын қосыңыз.
2. **Интеграциялар → 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)** тұрғанын тексеріңіз.

## Тапсырыс күйі қалай ауысады

1. Сатып алушы тапсырысты растағанда плагин `POST /api/v1/invoices` шақырады: `externalOrderId` — тапсырыс нөмірі, `Idempotency-Key` — `wc-{id}-…`. Сондықтан батырманы екі рет бассаңыз да екі счёт шықпайды. Сатып алушы `payUrl` бетіне бағытталады.
2. Счёт `pending` күйінде шамамен 3 минут тұрады — бұл Kaspi-дің QR сканерлеу терезесі.
3. Төленсе — webhook `invoice.paid` келеді, тапсырыс сіз таңдаған күйге ауысады, тапсырыс ескертпелерінде «Qut Pay: оплачен, счёт inv_…» жазылады.
4. Төленбесе — счёт `expired` болады, тапсырыс «Отменён» күйіне көшеді.
5. **Кеш төлем.** Счёт жабылғаннан кейін ақша келсе, `invoice.paid` кейін де келеді және тапсырысты қайта «оплачен» етеді. Бұл қалыпты жағдай: не тауарды беріңіз, не ақшаны қайтарыңыз.

«Спасибо» бетінде плагин күйді API-дан қайта сұрайды — webhook кешіксе де сатып алушы дұрыс күйді көреді. Бір оқиға екі рет келсе, тапсырыс екі рет өзгермейді.

## Қайтару

Қайтаруды WooCommerce-тің өз тапсырыс карточкасынан жасайсыз: тапсырысты ашып, **«Возврат»** батырмасын басыңыз. Плагин `POST /invoices/{id}/refund` шақырады. Ішінара қайтару да жұмыс істейді.

Шарты біреу: **кілтте `refunds:write` рұқсаты болуы керек.** Кілт жасағанда оны белгілемесеңіз, қайтару 403 қатесімен өтпейді — жаңа кілт жасап, плагиндегі мәнді ауыстырыңыз.

Қайтаруды кабинеттен де жасауға болады — ол кезде тапсырыс webhook арқылы жаңарады.

## Чек

Төленген соң чек сілтемесі «Спасибо» бетінде шығады және тапсырыс ескертпесіне жазылады. Счёт жасағанда сатып алушының email-і берілсе, чек хаты да кетеді (кабинетте SMTP бапталған болса). Толығырақ: [Чектер](/kb/receipts).

## Сынау

**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` жоқ. Жаңа кілт жасаңыз |

Егер тізімдегі тексерулер көмектеспесе: [Плагин істемей жатыр](/kb/plugin-not-working).

## Жиі қойылатын сұрақтар

**Checkout Blocks-пен жұмыс істей ме?** Иә. Классикалық касса да, Blocks та, HPOS та қолдау көрсетіледі.

**Сайтым http арқылы ашылады.** Live режимде webhook адресі міндетті түрде https болуы керек. Сертификат орнатыңыз — қазір ол тегін.

**Бірнеше дүкенім бар, бір кілт жетеді ме?** Әр сайтқа бөлек кілт жасап, webhook адресін сол кілтке байлаған дұрыс: сонда әр дүкен тек өз оқиғаларын алады.

**Сатып алушы төлем бетінен қайтып кетсе не болады?** Тапсырыс «Ожидает оплаты» күйінде қалады, счёт өз мерзімінде `expired` болады. Сатып алушы тапсырысты қайта ашып, төлей алады.

**Тапсырыс күйін өзім ауыстырсам, плагин оны қайта өзгерте ме?** Менеджер тапсырысты processing немесе complete күйіне қойған болса, кешіккен `expired`/`cancelled` оқиғасы оны қайта өзгертпейді.

**OpenCart дүкені үшін не істеу керек?** Ол үшін бөлек кеңейту бар: [OpenCart 4 кеңейтуі](/kb/opencart).