Qut PayСайтКабинетБілім базасыAPI (OpenAPI)AI-нұсқаулықРУСҚАЗEN

Баланс толтыру пакеттері (ЖИ-сервис, SaaS, сайт)

Сервисіңізде ішкі баланс бар ма — ЖИ-чат, генерация, SaaS кабинеті, онлайн-курс? Клиент «Толтыру» батырмасын басады, Kaspi арқылы төлейді, сіздің жүйеңіз балансты толтырады. Qut Pay бұған екі жол береді:

  1. Пакеттері бар төлем сілтемесі — кодсыз: кабинетте 2–6 пакет («5 000 ₸ — 600 сұрақ»), сілтемеге ?ref=<клиент id> қосасыз.
  2. API / SDK — createTopUp({ userRef, amount, pack }): өз бетіңізде батырма, клиент Qut Pay төлем бетіне өтеді.

Екеуінде де төленген счёт webhook-та invoice.metadata.ref (кімге) және metadata.qutpay_kind = "topup" белгісімен келеді.

Балансты сіздің жүйеңіз сақтайды. Qut Pay ақшаны да, балансты да ұстамайды: ақша клиенттен тікелей сіздің Kaspi Pay шотыңызға түседі. Qut Pay счёт жасайды және төлем туралы хабарлайды.

Telegram туралы маңызды ескерту

Telegram ережелері бойынша бот немесе мини-қосымша ішінде сатылатын цифрлық тауар мен қызмет (ЖИ-сұрақтар, жазылым, контент) тек Telegram Stars арқылы төленуі керек; басқа төлем жүйесін қолданған боттар мобильді қосымшада жасырылуы мүмкін. Сондықтан:

1-жол: пакеттері бар сілтеме (кодсыз)

  1. Кабинет → Сілтемелер → атауын жазыңыз (мысалы «ЖИ балансы») → Баланс пакеттері батырмасы.
  2. Әр жолға бір пакет: сома;атауы, 2–6 жол: `` 2000;2 000 ₸ — 200 сұрақ 5000;5 000 ₸ — 600 сұрақ 10000;10 000 ₸ — 1 300 сұрақ `` Атауы — 60 таңбаға дейін, бос қалса сома жазылады. Сомалар әртүрлі болуы керек.
  3. Құру. Сілтеме бетінде сома өрісінің орнына пакет батырмалары шығады. Клиент тек осы сомалардың бірін төлей алады — басқа соманы сервер қабылдамайды.
  4. Сайтыңызда әр пайдаланушыға өз сілтемесін беріңіз: `` https://qut.kz/p/ai-packs?ref=user_42 ` ref — 1–64 таңба: латын әріптері, сандар, _ . : -. Ол төлем бетінің формасы арқылы счёттың metadata.ref` өрісіне түседі.

Төленген счёттың metadata:

{ "paymentLinkId": "pl_…", "slug": "ai-packs", "ref": "user_42", "qutpay_kind": "topup", "pack": "5 000 ₸ — 600 сұрақ", "packIndex": 1 }

Кабинетте пакеттері бар сілтеменің жанындағы Толтырулар батырмасы ref бойынша жинақты көрсетеді: төлем саны, сома (қайтарулар шегерілген), соңғы төлем.

ref қолтаңбасыз. Біреу сілтемедегі ref-ті өзгертсе, ол тек басқа адамның балансын өз ақшасына толтырады — ешкімнің ақшасын ала алмайды. Ref-ті қатаң байлау керек болса (мысалы, клиент өз id-ін көрмеуі керек), 2-жолды қолданыңыз: счётты серверіңіз жасайды.

2-жол: API / SDK

Node.js (@qutpay/sdk 0.1.1+):

import { QutPay, verifyWebhook } from '@qutpay/sdk';
const qp = new QutPay({ apiKey: process.env.QUTPAY_API_KEY });

app.post('/topup', async (req, res) => {
  const inv = await qp.createTopUp({
    userRef: req.user.id,            // кімнің балансы
    amount: 5000,
    pack: 'pro-600',                  // metadata.pack-та қайтады
    idempotencyKey: `topup-${req.user.id}-${Date.now()}`,
    successUrl: 'https://my-ai.kz/balance',
  });
  res.redirect(inv.payUrl);
});
// пакеттері бар сілтеме: qp.topUpLink('ai-packs', req.user.id) → https://qut.kz/p/ai-packs?ref=…

Python (qutpay.py 0.1.1+):

inv = qp.create_top_up(user.id, 5000, pack="pro-600", idempotency_key=f"topup-{user.id}-{int(time.time())}")
return redirect(inv["payUrl"])

PHP (QutPay.php):

$inv = $qp->createTopUp((string) $user->id, 5000, ['pack' => 'pro-600', 'idempotencyKey' => 'topup-' . $user->id . '-' . time()]);
header('Location: ' . $inv['payUrl']);

Кодсыз API: POST /api/v1/invoices денесі { "amount": 5000, "kind": "qr", "description": "Баланс толтыру", "metadata": { "ref": "user_42", "pack": "pro-600", "qutpay_kind": "topup" } }. MCP-де: qutpay_create_topup құралы. n8n: qutpay-create-topup.json workflow.

Webhook өңдеу

app.post('/qutpay/webhook', express.raw({ type: '*/*' }), async (req, res) => {
  if (!verifyWebhook({ secret: process.env.QUTPAY_WEBHOOK_SECRET, rawBody: req.body, headers: req.headers })) return res.sendStatus(401);
  const { event, invoice } = JSON.parse(req.body);
  if (invoice.metadata?.qutpay_kind !== 'topup') return res.sendStatus(200);
  if (event === 'invoice.paid') {
    // бір счётқа бір рет: invoice.id — бірегей кілт (unique index)
    await db.creditOnce(invoice.id, invoice.metadata.ref, invoice.amount);
  }
  if (event === 'invoice.refunded' || event === 'invoice.partially_refunded') {
    // invoice.refundedAmount — жалпы қайтарылған сома; бұрын шегерілгенін алып тастаңыз
    await db.debitRefund(invoice.id, invoice.refundedAmount);
  }
  res.sendStatus(200);
});

Ережелер:

Шектеулер

Дайын мысал

Express-тегі шағын веб-қосымша: «Баланс» беті, «Толтыру» батырмалары, webhook өңдеу (идемпотенттілік, қайтару) — https://api.qut.kz/downloads/qutpay-topup-web.zip. Ішінде README (қазақша, орысша) және желісіз тесттер.

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

Qut Pay балансты сақтай ма? Жоқ. Баланс — сіздің дерекқорыңызда. Qut Pay счёт жасайды және төлем туралы webhook жібереді.

Telegram-ботта ЖИ-сұрақтарды сатуға бола ма? Telegram ішіндегі цифрлық тауар — тек Telegram Stars арқылы. Клиентті сайтқа жіберіп, сол жерде баланс толтыру — сіздің жауапкершілігіңіздегі шешім; Telegram ережелерін өзіңіз тексеріңіз.

Клиент ref-ті өзгертсе не болады? Ол басқа адамның балансын өз ақшасымен толтырады. Қатаң байлау керек болса — счётты серверден createTopUp арқылы жасаңыз.

Автоматты түрде ай сайын толтыруға бола ма? Жоқ: әр толтыруды клиент Kaspi-де өзі растайды. Тұрақты төлемге «Жазылымдар» (счёт кестесі) бар — счёт келеді, клиент өзі төлейді.

Sandbox-та қалай тексеремін? qp_test_… кілтімен счёт жасаңыз, POST /api/v1/invoices/{id}/simulate { "status": "paid" } немесе төлем бетіндегі «[Sandbox] төлеу» — webhook нақты жіберіледі.


Көмек керек пе? WhatsApp +77788813333 · kazprose@gmail.com · 09:00–21:00 (Алматы)
Кабинеттен де жазуға болады: Қолдау.

Qut Pay — тәуелсіз сервис, «Kaspi Bank» АҚ-мен аффилирленбеген. Kaspi және Kaspi Pay — құқық иесінің тауар белгілері.