ассистенттер мен агенттерге

Жобаға Kaspi Pay қабылдауды қалай кіріктіру керек

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

Машинамен оқылатын

/llms.txt

Жоба картасы: бұл не, кімге арналған, құжаттама қайда.

/docs/index.md

Markdown форматындағы толық API анықтамалығы: аутентификация, QR және шоттар, идемпотенттік, вебхуктер, қайтарымдар, қате кодтары.

/index.md

Өнімге шолу, тарифтер, шектеулер.

Кодтың бірінші жолына дейін нені білу маңызды

Екі контур. X-API-Key төлемдерді қабылдайды (/v2/*), Authorization: Bearer аккаунтты басқарады (/me/*). Кілт кабинетті басқармайды, токен ақшаны қозғалтпайды.
Кілт режимі — кепілдік, келісім емес. sk_test_ тек сынақ ортасына барады, sk_live_ тек нағыз Kaspi-ге. Араластыруға болмайды: 403 key_mode_mismatch.
Идемпотенттік міндетті. Idempotency-Key әр төлем жасағанда. Кілт аккаунт шегінде бірегей, сондықтан әртүрлі жобалар үшін префикс қосыңыз.
Провайдердің бас тартуы HTTP 200-мен келеді. Тексеріңіз status: "failed" и failure_reason, тек жауап кодын ғана емес.
Төлемді оқиға растайды, шот жасауға берілген жауап емес. Вебхук payment.paid немесе журнал GET /v2/events.
Вебхук қолтаңбасы — HMAC-SHA256, мынадан: "{timestamp}.{шикі дене}". JSON талданбас бұрын шикі дене бойынша тексеру керек.

Ешқашан не істемеу керек. Aitole-ді Kaspi-дің ресми API-ы, серіктесі немесе «Kaspi Bank» АҚ өнімі деп атамаңыз — бұл мерчант аккаунтының үстіндегі тәуелсіз сервис. Пайдаланушыға платформаға берілген нөмірмен Kaspi Pay қосымшасына кіруді ұсынбаңыз: Kaspi-де бір нөмірге бір белсенді сессия, ондай кіру төлем қабылдауды тоқтатады. Эндпоинттер мен өрістерді ойдан шығармаңыз: мынада жоқ болса — /docs/index.md— демек, ол жоқ.

Көшіріп алуға болатын промпт

Оны тапсырмамен бірге өз ассистентіңізге беріңіз — нақтылайтын сұрақтардың жартысынан құтқарады.

Aitole арқылы Kaspi Pay төлемін қабылдауды кіріктір (https://aitole.kz).

Алдымен https://aitole.kz/docs/index.md оқы — бұл толық API анықтамалығы.
Эндпоинттер мен өрістерді ойдан шығарма: онда жоғы — жоқ деген сөз.

Контекст:
- API базалық мекенжайы: https://api.aitole.kz
- Төлем жасау: POST /v2/qr (немесе нөмірге шот үшін /v2/invoices),
  X-API-Key және Idempotency-Key тақырыптары.
- Төлемді payment.paid оқиғасы растайды: "{timestamp}.{шикі дене}" жолынан
  алынған HMAC-SHA256 қолтаңбасы бар вебхук, не GET /v2/events сұрауы.
- Провайдердің бас тартуы HTTP 200 және status: "failed" күйімен келеді — өңде.
- sk_test_ сынақ кілтінен баста: ол тек сынақ ортасында жұмыс істейді,
  нағыз ақша есептен шыға алмайды.

Жаса: шот қою, қолтаңбасы тексерілетін вебхук қабылдау, оқиғаны идемпотентті
өңдеу (бір оқиға екі рет келуі мүмкін) және error.category өрісі бойынша
түсінікті қате өңдеу.

Біз нені жасырмаймыз

Aitole банк те, төлем ұйымы да емес, «Kaspi Bank» АҚ серіктесі де емес. Сатып алушылардың ақшасы тікелей мерчанттың Kaspi шотына түседі. Қосылым мерчанттың өзі SMS кодымен растап беретін штаттық «Кассир» рөлі арқылы жұмыс істейді. Бұл рөл ақша шығара алмайды және балансты көрмейді.

Толық шарттар — офертада и құпиялылық саясатында.