Қысқаша
Кеңейту 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-қадам. Орнату
- Әкімшілік панель → Extensions → Installer → Upload →
qutpay.ocmod.zipфайлын таңдаңыз. Жүктелген соң «Qut Pay (Kaspi QR)» жолының қасындағы жасыл Install батырмасын басыңыз. - Extensions → Extensions → Payments тізімінен «Qut Pay (Kaspi QR)» жазбасын тауып, жасыл плюс батырмасын басыңыз. Осы сәтте
oc_qutpay_invoiceкестесі жасалады. - Сол жерден Edit басып, баптауға көшіңіз.
2-қадам. Кілт пен webhook
Кабинет: https://qut.kz/app
- Интеграциялар → API кілттері → атауы ретінде дүкеніңізді жазып, Жасау. Кілт бір рет көрсетіледі, бірден көшіріп алыңыз.
- Кеңейту баптауындағы «Адрес webhook» өрісі оқуға ғана арналған — оны көшіріңіз. Ол мынадай түрде болады:
`` https://ДҮКЕНІҢІЗ/index.php?route=extension/qutpay/payment/qutpay.webhook ``
- Кабинет → Интеграциялар → 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). Дүкеніңізде күйлер өзгертілген болса, тізімнен қолмен таңдаңыз.
Тапсырыс күйі қалай ауысады
- Растау қадамында сатып алушы батырманы басады. Кеңейту
POST /api/v1/invoicesшақырады: сома, «Дүкен атауы — заказ №N» сипаттамасы,externalOrderId— тапсырыс нөмірі,customer(телефон7XXXXXXXXXXпішіміне келтіріледі),metadataішінде дүкен мен тапсырыс белгілері,Idempotency-Key—oc-{тапсырыс}-…. - Счёт
oc_qutpay_invoiceкестесіне жазылады, тапсырысқа «Ожидание оплаты» күйі қойылады, сатып алушыpayUrlбетіне бағытталады. Сатып алушы қайтып келіп, батырманы қайта бассa, ал ескі счёт әлі ашық және сома өзгермеген болса — солpayUrlқайта пайдаланылады. - Webhook келгенде қолтаңба өзгертілмеген дене бойынша тексеріледі, 5 минуттан ескі белгі қабылданбайды. Өңдеу (счёт, күй) жұбы бойынша идемпотентті.
| Оқиға | Не болады |
|---|---|
paid | «Оплачен» күйі, тарихқа чек нөмірі мен сілтемесі жазылады. Счёт сомасы тапсырыс сомасына сәйкес келмесе — күй өзгермейді, тарихқа ескерту түседі |
expired / cancelled | Сәйкес күй, бірақ тапсырысты менеджер processing/complete етіп қойған болса — тимейді |
refunded | «Возврат» күйі |
partially_refunded | Тек тарихқа жазба |
Кеш төлем (late: true) | Счёт өтіп кеткен болса да тапсырыс төленген деп белгіленеді |
- Сатып алушы қайтқанда кеңейту
GET /api/v1/invoices/{id}?live=1сұрайды. Счёт төленген болса — стандарттыcheckout/successбетіне жібереді (себет тазарады). Әйтпесе күту беті көрсетіледі: «Проверить ещё раз» (8 секунд сайын өзі жаңарады), «Открыть страницу оплаты Kaspi», «Вернуться к оформлению».
Webhook жауаптары: 200 — қабылданды, 401 — қолтаңба жарамсыз, 400 — дене бұзылған, 503 — кеңейту өшірулі немесе құпия қойылмаған.
Қайтару
Әкімшілік панельден қайтару жасалмайды. Қайтаруды Qut Pay кабинетінен жасаңыз: Счёттар → счётты ашу → Қайтару. Содан кейін invoice.refunded оқиғасы келіп, OpenCart тапсырысы сіз таңдаған «Возврат» күйіне ауысады.
Ішінара қайтару жасасаңыз, тапсырыс күйі өзгермейді — тарихқа жазба ғана түседі. Қайтару туралы толығырақ: Қайтару 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 деп аталуы керек |
Толық диагностика: Плагин істемей жатыр.
Жиі қойылатын сұрақтар
OpenCart 3-те жұмыс істей ме? Жоқ. Кеңейту OpenCart 4.0.2.x бойынша жазылған. 3-нұсқада API-ді тікелей шақыруға болады: PHP SDK.
Бір API кілтпен екі дүкен жұмыс істей ме? Иә, бірақ кеңейту тапсырыс белгісін счёт metadata ішінде сақтап, webhook-та салыстырады: бөтен дүкеннің счёты бойынша келген оқиға еленбейді. Дегенмен әр дүкенге бөлек кілт беру ыңғайлырақ.
Логты қайдан қараймын? «Лог отладки» қосулы болса — storage/logs/qutpay.log.
Сатып алушы төлемей кетсе не болады? Счёт өз мерзімінде expired болады, тапсырыс сіз таңдаған күйге көшеді. Сатып алушы тапсырысты қайта ашып, жаңа счёт ала алады.
WordPress дүкені үшін не бар? WooCommerce плагині: WooCommerce плагині.