# OpenCart 4 кеңейтуі

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

## Қысқаша

Кеңейту OpenCart 4 дүкеніне «Оплата через Kaspi (QR)» әдісін қосады: сатып алушы тапсырысты растайды → Qut Pay төлем бетіне өтеді (QR + Kaspi сілтемесі) → Kaspi қосымшасында төлейді. Тапсырыс күйі webhook арқылы автоматты жаңарады, ақша тікелей сіздің Kaspi Pay шотыңызға түседі.

Жүктеу: **https://api.qut.kz/downloads/qutpay.ocmod.zip**

Архивтің атауы маңызды: OpenCart кеңейту кодын (`qutpay`) файл атынан алады. Атын өзгертпеңіз.

## Талаптар

| Не | Мәні |
|---|---|
| OpenCart | 4.0.2.0 және жоғары |
| PHP | 8.0 және жоғары, `curl` мен `json` кеңейтулерімен |
| Дүкен валютасы | **KZT (₸)**. Басқа валютада әдіс кассада көрінбейді |
| Сайт | Интернеттен https арқылы қолжетімді болуы керек, әйтпесе продакшенде webhook жетпейді |
| Qut Pay | Kaspi кассирі қосылған ұйым (sandbox-та сынау үшін кассир керек емес) |

## 1-қадам. Орнату

1. Әкімшілік панель → **Extensions → Installer** → **Upload** → `qutpay.ocmod.zip` файлын таңдаңыз. Жүктелген соң «Qut Pay (Kaspi QR)» жолының қасындағы жасыл **Install** батырмасын басыңыз.
2. **Extensions → Extensions → Payments** тізімінен «Qut Pay (Kaspi QR)» жазбасын тауып, жасыл **плюс** батырмасын басыңыз. Осы сәтте `oc_qutpay_invoice` кестесі жасалады.
3. Сол жерден **Edit** басып, баптауға көшіңіз.

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

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

1. **Интеграциялар → API кілттері** → атауы ретінде дүкеніңізді жазып, **Жасау**. Кілт бір рет көрсетіледі, бірден көшіріп алыңыз.
2. Кеңейту баптауындағы **«Адрес webhook»** өрісі оқуға ғана арналған — оны көшіріңіз. Ол мынадай түрде болады:

   ```
   https://ДҮКЕНІҢІЗ/index.php?route=extension/qutpay/payment/qutpay.webhook
   ```

3. Кабинет → **Интеграциялар → Webhook** → сол адресті қосыңыз, «Кілт» тізімінен жаңа кілтті таңдаңыз → **Жасау**. Көрсетілген құпияны көшіріп, кеңейтудегі «Секрет webhook» өрісіне қойыңыз.

**Құпия болмаса тапсырыстар автоматты түрде төленген деп белгіленбейді** — кеңейту 503 қайтарады да, біз жеткізуді қайталай береміз.

## 3-қадам. Баптау

| Өріс | Не қою керек |
|---|---|
| API-ключ | 2-қадамдағы кілт. Қасындағы **«Проверить ключ»** батырмасы API-ге сұрау жіберіп, кілттің жарамдылығын тексереді |
| Адрес webhook | Оқуға ғана. Кабинетке көшіріңіз |
| Секрет webhook | Кабинетте адрес қосқанда бір рет көрсетілген мән |
| Адрес API | `https://api.qut.kz` — өзгертпеңіз |
| Ожидание оплаты | Тапсырыс расталып, сатып алушы төлем бетіне жіберілген сәттегі күй |
| Оплачен | Төлем расталған сәттегі күй. Цифрлық тауарға әдетте «Выполнен» |
| Счёт истёк / Счёт отменён / Возврат | Сәйкес күйлер. Қажет болмаса «не менять статус» таңдауға болады |
| Геозона, Статус, Порядок сортировки | Басқа төлем әдістеріндегідей |
| Лог отладки | Сынау кезінде қосыңыз: жазбалар `storage/logs/qutpay.log` файлына түседі |

**Статус** ауыстырғышын қосып, сақтаңыз.

Әдепкі күй идентификаторлары стандартты OpenCart орнатуына сай қойылған (1 Pending, 2 Processing, 14 Expired, 7 Canceled, 11 Refunded). Дүкеніңізде күйлер өзгертілген болса, тізімнен қолмен таңдаңыз.

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

1. **Растау қадамында** сатып алушы батырманы басады. Кеңейту `POST /api/v1/invoices` шақырады: сома, «Дүкен атауы — заказ №N» сипаттамасы, `externalOrderId` — тапсырыс нөмірі, `customer` (телефон `7XXXXXXXXXX` пішіміне келтіріледі), `metadata` ішінде дүкен мен тапсырыс белгілері, `Idempotency-Key` — `oc-{тапсырыс}-…`.
2. Счёт `oc_qutpay_invoice` кестесіне жазылады, тапсырысқа «Ожидание оплаты» күйі қойылады, сатып алушы `payUrl` бетіне бағытталады. Сатып алушы қайтып келіп, батырманы қайта бассa, ал ескі счёт әлі ашық және сома өзгермеген болса — сол `payUrl` қайта пайдаланылады.
3. **Webhook** келгенде қолтаңба өзгертілмеген дене бойынша тексеріледі, 5 минуттан ескі белгі қабылданбайды. Өңдеу (счёт, күй) жұбы бойынша идемпотентті.

| Оқиға | Не болады |
|---|---|
| `paid` | «Оплачен» күйі, тарихқа чек нөмірі мен сілтемесі жазылады. Счёт сомасы тапсырыс сомасына сәйкес келмесе — күй өзгермейді, тарихқа ескерту түседі |
| `expired` / `cancelled` | Сәйкес күй, бірақ тапсырысты менеджер processing/complete етіп қойған болса — тимейді |
| `refunded` | «Возврат» күйі |
| `partially_refunded` | Тек тарихқа жазба |
| Кеш төлем (`late: true`) | Счёт өтіп кеткен болса да тапсырыс төленген деп белгіленеді |

4. **Сатып алушы қайтқанда** кеңейту `GET /api/v1/invoices/{id}?live=1` сұрайды. Счёт төленген болса — стандартты `checkout/success` бетіне жібереді (себет тазарады). Әйтпесе күту беті көрсетіледі: «Проверить ещё раз» (8 секунд сайын өзі жаңарады), «Открыть страницу оплаты Kaspi», «Вернуться к оформлению».

Webhook жауаптары: `200` — қабылданды, `401` — қолтаңба жарамсыз, `400` — дене бұзылған, `503` — кеңейту өшірулі немесе құпия қойылмаған.

## Қайтару

**Әкімшілік панельден қайтару жасалмайды.** Қайтаруды Qut Pay кабинетінен жасаңыз: **Счёттар → счётты ашу → Қайтару**. Содан кейін `invoice.refunded` оқиғасы келіп, OpenCart тапсырысы сіз таңдаған «Возврат» күйіне ауысады.

Ішінара қайтару жасасаңыз, тапсырыс күйі өзгермейді — тарихқа жазба ғана түседі. Қайтару туралы толығырақ: [Қайтару API](/kb/refunds-api).

## Сынау

Sandbox кілтімен (`qp_test_…`) тапсырыс жасаңыз. Төлем бетінде «[Sandbox] төлеу» батырмасы болады, ол төлемді имитациялайды — webhook бұл кезде шынайы жіберіледі, күйлердің дұрыс ауысқанын толық тексере аласыз.

Live-қа көшкенде `qp_live_…` кілтін қойып, шағын сомаға бір тапсырыс жасап тексеріңіз.

## Жиі кездесетін мәселелер

| Белгісі | Себебі және шешімі |
|---|---|
| Кассада әдіс көрінбейді | Валюта KZT емес; кеңейту Payments тізімінде орнатылмаған; Статус өшірулі; геозона сәйкес емес |
| Тапсырыс «Ожидание оплаты» күйінде қалады | Webhook кабинетте тіркелмеген, адрес қате немесе құпия сәйкес емес. Кабинеттегі жеткізу журналын қараңыз |
| Журналда 503 | Кеңейту өшірулі немесе «Секрет webhook» өрісі бос |
| Журналда 401 | Құпия дұрыс емес. Кабинетте адресті қайта қосып, жаңа құпияны қойыңыз |
| Webhook мүлде келмейді | Дүкен Maintenance режимінде тұр — ол кіріс сұрауларды бөгейді. Режимнен шыққан соң күй сатып алушы қайтқанда да түзеледі |
| «Проверить ключ» қате береді | Кілт қате көшірілген немесе режимі сәйкес емес: sandbox ұйымға `qp_test_…`, live-қа `qp_live_…` |
| Webhook адресі дұрыс емес | Адрес әкімшіліктегі `HTTP_CATALOG` мәнінен құралады. Дүкен прокси артында немесе бөлек доменде болса, адресті қолмен түзетіп, кабинетке дұрысын тіркеңіз |
| Кеңейту Installer-де көрінбейді | Архив атауы өзгертілген. Файл `qutpay.ocmod.zip` деп аталуы керек |

Толық диагностика: [Плагин істемей жатыр](/kb/plugin-not-working).

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

**OpenCart 3-те жұмыс істей ме?** Жоқ. Кеңейту OpenCart 4.0.2.x бойынша жазылған. 3-нұсқада API-ді тікелей шақыруға болады: [PHP SDK](/kb/sdk-php).

**Бір API кілтпен екі дүкен жұмыс істей ме?** Иә, бірақ кеңейту тапсырыс белгісін счёт `metadata` ішінде сақтап, webhook-та салыстырады: бөтен дүкеннің счёты бойынша келген оқиға еленбейді. Дегенмен әр дүкенге бөлек кілт беру ыңғайлырақ.

**Логты қайдан қараймын?** «Лог отладки» қосулы болса — `storage/logs/qutpay.log`.

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

**WordPress дүкені үшін не бар?** WooCommerce плагині: [WooCommerce плагині](/kb/woocommerce).