Онлайн мектеп пен курс платформасына

Қысқаша

Онлайн мектепте бүкіл жұмыс бір тізбекке құрылады: счёт → төлем → webhook → қолжетімділік. Оқушы курсты таңдайды, сіз счёт жасайсыз, ол Kaspi арқылы төлейді, сізге invoice.paid келеді де, сіздің платформаңыз сол сәтте курсты ашады. Кезеңдік төлем үшін жазылым бар, ол счётты кестеге сай өзі шығарады — бірақ ақша өздігінен алынбайды, әр төлемді оқушы Kaspi-де өзі растайды.

Негізгі сценарий: курсқа кіру

POST /api/v1/invoices
{
  "amount": 39000,
  "kind": "qr",
  "description": "«Python негіздері» курсы, 2 ағым",
  "externalOrderId": "ENR-8842",
  "customer": { "name": "Айдана", "email": "aidana@example.kz" },
  "successUrl": "https://school.kz/enroll/8842/done",
  "failUrl": "https://school.kz/enroll/8842/retry",
  "metadata": { "user_id": "3311", "course_id": "py-basics", "cohort": "2" }
}

• successUrl мен failUrl — тек http(s). Клиент төлегеннен кейін сол бетке қайтады.
• successUrl-ды қолжетімділік ашудың белгісі деп санамаңыз. Ол жай ғана бет. Клиент оны қолмен ашып қоя алады, ал шынайы төлем расталуы webhook арқылы келеді.
• metadata ішінде user_id мен course_id болсын — webhook қайтқанда кімге не ашатыныңызды сол арқылы табасыз.
• Idempotency-Key тақырыбын жіберіңіз: оқушы «Төлеу» батырмасын екі рет басса, екі счёт жасалмайды.

Оқушы сайтта отырса kind: "qr" ыңғайлы: беттегі QR-ды телефонымен сканерлейді немесе payUrl арқылы өтеді. Ал WhatsApp пен Instagram-да сөйлесіп жатсаңыз, kind: "phone" ыңғайлырақ — Kaspi-іне бірден push келеді, description онда 60 таңбадан аспайды.

Webhook арқылы қолжетімділікті ашу

Бұл ең маңызды бөлігі. Реті:

1. Кабинет → Интеграциялар бөлімінде webhook адресін қосасыз. Продакшенде тек https және нақты домен: IP мен туннель адресі қабылданбайды.
2. Құпия бір рет көрсетіледі — сақтап қойыңыз.
3. Адресіңіз авторизациясыз ашық болуы керек. Басқа жерге апаратын қайта бағыттау ұсталмайды.
4. Қолтаңбаны тексересіз: HMAC-SHA256(secret, timestamp + "." + rawBody), hex, sha256= префиксімен. Денені өзгертілмеген байт күйінде тексеріңіз, JSON-ға айналдырғанға дейін. 5 минуттан ескі timestamp қабылданбасын.
5. invoice.paid келгенде metadata.user_id мен metadata.course_id бойынша курсты ашасыз.
6. 2xx қайтарасыз. Қайтармасаңыз жеткізу 11 рет қайталанады (10 секундтан бір сағатқа дейін өсіп).

Өңдеуіңіз идемпотентті болсын: (invoice.id, status) жұбын сақтап, қайталанғанын елеңіз. Әйтпесе бір оқушыға он бір рет «қош келдіңіз» хаты кетеді.

Толығырақ: Webhook баптау, Webhook қауіпсіздігі, Webhook келмей жатыр.

Кезеңдік төлем

Ай сайынғы жазылым, транш бойынша оқу ақысы, «курс + қолдау» форматы — бәрі жазылым арқылы.

• Аралық: month (әдепкі жағдай), week, day; кратность every.
• Қайталау сатысы retryDelaysMin, әдепкі [15, 60, 360] минут, ең көбі 5 мән. Оқушы счётты бірден көрмесе, қайта шығады.
• Саты біткенде сол кезең тасталады, кесте келесі кезеңге жалғасады. failedRuns, lastError, lastRunStatus өрістері бар.
• Өткізіп алу саясаты misfirePolicy: run_once (әдепкі) немесе skip, misfireAfterMin әдепкі 1440.
• Оқушы демалысқа шықса — pause, қайтып келгенде resume. Өткен кезекті бірден жіберу керек болса, POST /subscriptions/{id}/resume { catchUp: true }.

Қолжетімділікті жабуды өзіңіз шешесіз. Жазылым төленбесе, біз курсты жаппаймыз — біз тек счёт шығардық және ол төленбегенін хабарлаймыз. Сіздің платформаңыз «төленбеген кезең» дегенді көріп, қолжетімділікті жабады немесе қалдырады.

Толығырақ: Жазылымдық бизнеске.

Топтық тариф және жеңілдік

Жеңілдік. Соманы сіз есептейсіз. Промокод, ерте тіркелу бағасы, әлеуметтік жеңілдік — бәрі сіздің жағыңызда шешіледі, счётқа дайын соманы бересіз. Qut Pay жеңілдік санамайды, промокод жүйесі жоқ.

Топтық тариф. Компания қызметкерлерін оқуға жіберсе немесе ата-аналар тобы бірге тіркелсе, екі жол бар:

Топтап шығарғанда әр элемент бөлек тексеріледі: біреуі қате болса, қалғандары жасала береді. Жауапты элемент бойынша қарап шығып, құлағандарын қайта жіберіңіз.

Мобильді қосымшаңыз болса

Мұнда абай болу керек. App Store мен Play Market ережесі бойынша цифрлық тауарды сыртқы төлеммен сатуға болмайды. Курсқа кіру, жазылым, платформа ішіндегі премиум — бұлар цифрлық тауар. Ал нақты тауар, жеткізу, офлайн қызмет ақысы, брондау — рұқсат.

Іс жүзінде онлайн мектептің көбі мына жолмен жүреді: төлем сайтта (браузерде) жасалады, қосымша тек дайын қолжетімділікті көрсетеді. Қосымшаның ішінен төлеуге сілтеме қою да дүкендердің ережесіне қайшы келуі мүмкін — ережені өзіңіз оқып, өз тәуекеліңізді бағалаңыз.

Техникалық жағы бөлек: қосымша бізге тікелей жүгінбейді. Реті — қосымша → өз серверіңіз → Qut Pay → Kaspi. API кілт тек серверде болуы керек, APK немесе IPA ішіне салуға болмайды. Толығырақ: Мобильді қосымшаға қосу.

Кодсыз нұсқасы

• Тұрақты төлем сілтемелері. Әр курсқа бір сілтеме: qut.kz/p/<slug>. Instagram профиліне, Telegram арнасына, лендингке қоясыз. Төлемді кабинеттен көріп, қолжетімділікті қолмен ашасыз: Төлем сілтемелері.
• Tilda немесе кез келген форма. Тіркелу формасынан счёт шығару форма-хук арқылы жасалады: Tilda және кез келген форма.
• WordPress сайты болса WooCommerce плагині бар: WooCommerce плагині.
• Telegram бот арқылы сату. Курсты ботта сатып, төлемнен кейін жабық арнаға шақыру жіберуге болады: Telegram ботында тауар сату.
• n8n. Счёт жасау мен webhook қабылдаудың дайын workflow-лары бар.

Ерекше ескертулер

• Қолжетімділікті тек invoice.paid ашсын. invoice.created мен invoice.pending — төлем емес.
• Кеш келген төлем. Счёт expired болғаннан кейін де ақша келіп, invoice.paid late: true белгісімен келуі мүмкін. Курсты ашасыз немесе ақшаны қайтарасыз: Кеш келген төлем.
• API кілтті фронтендке салмаңыз. Ол тек серверде. Браузерде орындалатын JS-те кілт болса, ол шықты деп есептеңіз: API кілт сыртқа шығып кетті.
• Сатылымның шыңына дайын болыңыз. Ағым ашылған күні счёт саны бірнеше есе өседі. Айлық лимит пен тәуліктік қорғаныс — екі бөлек нәрсе: Тарифтер және лимиттер.
• Оқушыны қайтару саясатыңызбен алдын ала таныстырыңыз. Техникалық жағынан толық та, ішінара да қайтара аласыз: Қайтару API.

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

Төлемнен кейін курс бірден ашыла ма? Иә, invoice.paid webhook әдетте 5 секунд ішінде келеді, платформаңыз сол сәтте ашады.

Оқушы төледі, бірақ курс ашылмады. Не тексеремін? Алдымен webhook журналын: адрес қолжетімді ме, 2xx қайтардыңыз ба, қолтаңба сәйкес келді ме. Реті: Webhook келмей жатыр.

Промокод жасауға бола ма? Qut Pay жағында промокод жүйесі жоқ. Жеңілдікті өз платформаңызда есептеп, счётқа дайын соманы бересіз.

Жазылым төленбесе, сіздер курсты жабасыздар ма? Жоқ. Біз счёт шығарамыз және оның күйін хабарлаймыз, ал қолжетімділікті жабу-жаппауды сіздің платформаңыз шешеді.

Қосымшамнан төлем қабылдауға бола ма? Техникалық жағынан — иә, бірақ қосымша сервер арқылы жүреді. Ал App Store мен Play ережесі бойынша цифрлық тауарды сыртқы төлеммен сатуға болмайды, сондықтан онлайн курстарда төлемді браузерге шығарған қауіпсіз: Мобильді қосымшаға қосу.