Баланс толтыру пакеттері (ЖИ-сервис, SaaS, сайт)
Сервисіңізде ішкі баланс бар ма — ЖИ-чат, генерация, SaaS кабинеті, онлайн-курс? Клиент «Толтыру» батырмасын басады, Kaspi арқылы төлейді, сіздің жүйеңіз балансты толтырады. Qut Pay бұған екі жол береді:
- Пакеттері бар төлем сілтемесі — кодсыз: кабинетте 2–6 пакет («5 000 ₸ — 600 сұрақ»), сілтемеге
?ref=<клиент id>қосасыз. - 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 арқылы төленуі керек; басқа төлем жүйесін қолданған боттар мобильді қосымшада жасырылуы мүмкін. Сондықтан:
- Telegram-ботта Qut Pay — тек физикалық тауар мен офлайн қызмет үшін;
- Telegram ішіндегі цифрлық тауар → Telegram Stars;
- баланс пакеттері — сайттар, веб-сервистер, SaaS кабинеттері, WhatsApp-боттар үшін.
1-жол: пакеттері бар сілтеме (кодсыз)
- Кабинет → Сілтемелер → атауын жазыңыз (мысалы «ЖИ балансы») → Баланс пакеттері батырмасы.
- Әр жолға бір пакет:
сома;атауы, 2–6 жол: ``2000;2 000 ₸ — 200 сұрақ 5000;5 000 ₸ — 600 сұрақ 10000;10 000 ₸ — 1 300 сұрақ`` Атауы — 60 таңбаға дейін, бос қалса сома жазылады. Сомалар әртүрлі болуы керек. - Құру. Сілтеме бетінде сома өрісінің орнына пакет батырмалары шығады. Клиент тек осы сомалардың бірін төлей алады — басқа соманы сервер қабылдамайды.
- Сайтыңызда әр пайдаланушыға өз сілтемесін беріңіз: ``
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);
});
Ережелер:
- Идемпотенттілік. Бір оқиға қайта келуі мүмкін (жауап 2xx болмаса 11 рет қайталанады). Балансты счёт
idбойынша бір рет толтырыңыз. - Кеш төлем. QR мерзімі өткеннен кейін де төленуі мүмкін —
invoice.paidбәрібір келеді (late: true); оны да толтырыңыз. - Қайтару.
invoice.refunded/invoice.partially_refundedкелгенде қайтарылған соманы баланстан алыңыз. Клиент ақшаны жұмсап қойса, баланс минусқа түсуі мүмкін — оны қалай шешетініңізді өзіңіз анықтайсыз. - Webhook адресі: кабинет → Интеграциялар → Webhook.
Шектеулер
- Әр пакет — бір счёт. Төленгені тарифіңіздің айлық лимитіне кіреді (Тегін — 20, Бастау — 800, Бизнес — 4 000 төлем/ай); ашылып, төленбеген пакет есепке кірмейді. Күндік қорғаныс шегі бір күнде жасалған счёттарды санайды. «Бастау» тарифінде айлық лимиттің 80 %-ына жетсеңіз, ескерту хабарламасында «Бизнес» тарифі ұсынылады.
- Әр пакет — жеке Kaspi төлемі, әрқайсысына Kaspi комиссиясы алынады. Сондықтан пакетті 1 000 ₸-ден бастаған жөн; ұсақ төлемдерге (10–100 ₸) бұл тәсіл арналмаған.
- Бір сілтемеде 2–6 пакет, атауы 60 таңбаға дейін, бір пакет ең көбі 5 000 000 ₸.
- Бір IP бір сілтемеден 10 минутта ең көбі 10 счёт ашады.
Дайын мысал
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 — құқық иесінің тауар белгілері.