Қысқаша
Бұл бет — анықтама. Құжаттамада немесе кабинетте таныс емес сөз кездессе, осы жерден іздеңіз. Терминдер топталған: алдымен негізгі ұғымдар, сосын счёт түрлері, техникалық терминдер, ақша мен есеп, соңында тариф терминдері.
Негізгі ұғымдар
Кассир — Kaspi Pay-дегі шектеулі құқығы бар рөл: счёт шығару, күйін көру, өз счёттары бойынша қайтару жасау. Біз сол рөл арқылы жұмыс істейміз. Мысалы: Kaspi Pay қосымшасында Настройки → Сотрудники → Добавить сотрудника, рөлі «Кассир».
Байланыс (подключение) — кассир нөмірінің біздің сервиспен байланыстырылған күйі. Кабинеттің Kaspi бөлімінде әр байланыс жеке карточка болып тұрады. Байланыс үзілсе, счёт жасау тоқтайды.
API кілт — сіздің бағдарламаңыз бізге «мен пәленше ұйымның атынан келдім» деп айтатын құпия жол. X-API-Key тақырыбымен жіберіледі. Мысалы: qp_live_… немесе qp_test_…. Кілт тек серверде тұруы керек, браузерге де, мобильді қосымшаға да салуға болмайды.
Scope (құқық) — кілттің нені істей алатыны. Алтауы бар: invoices:read, invoices:write, refunds:write, subscriptions:manage, webhooks:manage, partner:manage. Мысалы: есеп жинайтын кілтке тек invoices:read беріңіз, сонда ол счёт жасай да, қайтара да алмайды.
Sandbox (тест режимі) — бәрі нақтысындай, бірақ Kaspi шақырылмайды және ақша жүрмейді. Кілті qp_test_…. Мысалы: интеграцияны sandbox-та жинап, төлемді өзіңіз имитациялап тексересіз.
Live (нақты режим) — нақты Kaspi QR, нақты ақша. Кілті qp_live_…. Кабинеттің жоғарғы жағында қай режимде екеніңіз жазулы тұрады.
Счёт және оның түрлері
Счёт (invoice) — клиенттен белгілі бір соманы сұрайтын жазба. Оның идентификаторы, сомасы, күйі, төлем беті болады. Күйлері: new → pending → paid / cancelled / expired.
QR счёт — клиент QR-ды сканерлеп немесе сілтемені ашып төлейтін счёт. Әдепкі түрі. Сипаттамасы 100 таңбаға дейін. Мысалы: кассадағы экранда QR көрсетесіз.
Телефонға счёт — клиенттің Kaspi қосымшасына тікелей келетін счёт, оған клиент нөмірі керек (7XXXXXXXXXX). Сипаттамасы 60 таңбаға дейін, сомасы бүтін теңге. Мысалы: телефон арқылы тапсырыс қабылдап, счётты бірден жібересіз.
Төлем сілтемесі — қайта-қайта қолдануға болатын тұрақты сілтеме, qut.kz/p/<slug> түрінде. Клиент ашқан сайын жаңа счёт жасалады. Мысалы: Instagram профиліне қоясыз немесе QR-ын басып шығарып кассаға жапсырасыз.
Ашық сома — сілтемеде сома бекітілмеген, клиент өзі енгізеді. Мин және макс шектеу қоюға болады. Мысалы: «Шығармашылық қолдау» немесе алдын ала сомасы белгісіз қызмет.
Техникалық терминдер
Webhook — төлем күйі өзгергенде біз сіздің серверіңізге жіберетін хабар. Сіз адресті кабинеттің Интеграциялар бөлімінде қоясыз. Мысалы: invoice.paid келді — тапсырысты «төленді» деп белгілейсіз.
Webhook құпиясы (secret) — хабардың шынымен бізден келгенін тексеретін кілт. Бір рет қана көрсетіледі. Қолтаңба HMAC-SHA256(secret, timestamp + "." + rawBody) түрінде есептеледі; денені өзгертілмеген байт күйінде, JSON-ға айналдырғанға дейін тексеру керек.
Идемпоттылық — бір әрекеттің екі рет орындалып кетпеуі. Счёт жасағанда Idempotency-Key тақырыбын қойсаңыз, сол кілтпен қайталанған сұрау жаңа счёт жасамайды, бұрынғысын қайтарады. Мысалы: интернет байланыс үзіліп, сұрау қайталанды — клиентке екі счёт кетпейді.
externalOrderId — сіздің өз тапсырыс нөміріңіз. Счётқа жазып қойсаңыз, webhook-та қайта келеді және кабинеттен іздеуге жарайды. Мысалы: "externalOrderId": "1001".
metadata — счётқа тіркейтін кез келген қосымша JSON. Бізге мағынасыз, сізге керек. Мысалы: {"table": "12", "waiter": "Асан"}.
Poller — счёттардың төленген-төленбегенін Kaspi-ден сұрап тұратын біздің механизм. Әр 3 секунд сайын жүреді, жас счёттар жиі тексеріледі. Іс жүзінде клиент төлегеннен кейін webhook әдетте 5 секунд ішінде келеді.
Ақша, қайтару, чек
Қайтару (refund) — төленген счёт бойынша ақшаны клиентке қайтару. POST /api/v1/invoices/{id}/refund, кабинетте Қайтару батырмасы.
Ішінара қайтару — соманың бір бөлігін ғана қайтару. Счёт partially_refunded күйіне өтеді. Мысалы: 10 000 ₸ тапсырыстың бір позициясы жоқ болып шықты, 2 500 ₸ қайтарасыз.
Чек — біздің төлем бетіміздегі чек, клиент оны сілтемеден көреді. Есеп жүргізуге ыңғайлы, бірақ фискалды құжат емес.
Фискалды чек — салық талабына сай құжат. Kaspi Касса қосулы болса, қашықтан төлемге чекті Kaspi өзі шығарып, клиентке жібереді. Чек беру міндеті сатушыда: біз ақшаны ұстамаймыз, сондықтан сіздің атыңыздан чек бере алмаймыз.
Кеш төлем — жабылған (cancelled немесе expired) счётқа ақшаның кешігіп келуі. Бұл жағдайда invoice.paid оқиғасы late: true белгісімен кейін де келуі мүмкін. Қызметті беру керек немесе ақшаны қайтару керек.
Жазылым және тариф
Жазылым (subscription) — счётты кестеге сай өздігінен шығару: күн, апта немесе ай аралығымен. Ақша клиенттің шотынан өздігінен алынбайды — жазылым тек счёт шығарады, төлемді клиент әр жолы өзі растайды. Мысалы: спортзал абонементі, ай сайын счёт.
Тариф — біздің қызметіміздің айлық ақысы: Бастау 4 990 ₸, Бизнес 14 900 ₸, Про 39 900 ₸. Транзакциядан пайыз алмаймыз.
Айлық лимит — тарифке кіретін счёт саны (мысалы, Бизнесте айына 4 000). Күнтізбелік ай бойынша, Алматы уақытымен есептеледі. Тірелсеңіз API tariff_limit_reached қатесін береді.
Тәуліктік қорғаныс — бір тәулікте жасалатын счёттың шегі (Бастауда 200, Бизнесте 1 500, Про тарифінде 5 000). Бұл бизнес лимиті емес, циклге түскен интеграциядан қорғаныс. Қатесі — tariff_daily_burst, айлық лимиттің қатесімен шатастырмаңыз.
Жиі қойылатын сұрақтар
Sandbox пен тест режимі — бір нәрсе ме? Иә, бір нәрсенің екі атауы.
Кассир мен қызметкер бір ме? Жоқ. Кассир — Kaspi Pay-дегі рөл. Қызметкер — біздің кабинетке шақырылған адам, ол өз нөмірімен кіреді.
Идемпоттылық қайда керек? Счёт жасауда (қосарланған счёт болмауы үшін) және webhook өңдеуде (бір оқиға екі рет келсе, тапсырысты екі рет жөнелтіп жібермеу үшін).
Термин мұнда жоқ болса? Қолдауға жазыңыз: WhatsApp +7 778 881 3333, Telegram @qutpaybot. Жиі сұралатынын осы бетке қосамыз.