Balance top-up packs (AI services, SaaS, websites)
Does your service have an internal balance — an AI chat, image generation, a SaaS dashboard, an online course? The customer presses "Top up", pays with Kaspi, and your system credits the balance. Qut Pay offers two ways:
- A payment link with packs — no code: 2–6 packs in the cabinet ("5,000 ₸ — 600 questions"), and you add
?ref=<customer id>to the link. - API / SDK —
createTopUp({ userRef, amount, pack }): a button on your own page sends the customer to the Qut Pay pay page.
Either way the paid invoice arrives in the webhook with invoice.metadata.ref (whom to credit) and the tag metadata.qutpay_kind = "topup".
Your system keeps the balance. Qut Pay holds neither the money nor the balance: the money goes from the customer straight to your own Kaspi Pay account. Qut Pay creates the invoice and tells you it was paid.
Important: Telegram
Under Telegram's rules, digital goods and services sold inside a bot or mini app (AI requests, subscriptions, content) must be paid with Telegram Stars only; bots that take other payments for digital goods may be hidden in the mobile apps. So:
- in a Telegram bot, use Qut Pay only for physical goods and offline services;
- digital goods inside Telegram → Telegram Stars;
- top-up packs are for websites, web services, SaaS dashboards and WhatsApp bots.
Way 1: a link with packs (no code)
- Cabinet → Links → a title (e.g. "AI balance") → the Top-up packs button.
- One pack per line,
amount;label, 2–6 lines: ``2000;2,000 ₸ — 200 questions 5000;5,000 ₸ — 600 questions 10000;10,000 ₸ — 1,300 questions`` A label is up to 60 characters; an empty one becomes the amount. Amounts must differ. - Create. The link page shows pack buttons instead of the amount field. Only these amounts can be paid — the server refuses any other.
- On your site give each user their own link: ``
https://qut.kz/p/ai-packs?ref=user_42`refis 1–64 characters: Latin letters, digits,_ . : -. The pay page form carries it into the invoice'smetadata.ref`.
metadata of the paid invoice:
{ "paymentLinkId": "pl_…", "slug": "ai-packs", "ref": "user_42", "qutpay_kind": "topup", "pack": "5,000 ₸ — 600 questions", "packIndex": 1 }
In the cabinet, a link with packs has a Top-ups button: a summary per ref — number of payments, amount after refunds, last payment.
ref is not signed. Someone who edits the ref in the link only tops up another person's balance with their own money — nobody's money can be taken this way. If you need a strict binding (e.g. the customer must not see their id), use way 2: your server creates the invoice.
Way 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, // whose balance
amount: 5000,
pack: 'pro-600', // comes back as metadata.pack
idempotencyKey: `topup-${req.user.id}-${Date.now()}`,
successUrl: 'https://my-ai.kz/balance',
});
res.redirect(inv.payUrl);
});
// link with packs: 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']);
Without an SDK: POST /api/v1/invoices with { "amount": 5000, "kind": "qr", "description": "Balance top-up", "metadata": { "ref": "user_42", "pack": "pro-600", "qutpay_kind": "topup" } }. MCP: the qutpay_create_topup tool. n8n: the qutpay-create-topup.json workflow.
Handling the 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') {
// once per invoice: invoice.id is a unique key (unique index)
await db.creditOnce(invoice.id, invoice.metadata.ref, invoice.amount);
}
if (event === 'invoice.refunded' || event === 'invoice.partially_refunded') {
// invoice.refundedAmount is the total refunded so far; subtract only what you have not yet
await db.debitRefund(invoice.id, invoice.refundedAmount);
}
res.sendStatus(200);
});
Rules:
- Idempotency. An event may arrive again (up to 11 attempts while the answer is not 2xx). Credit once per invoice
id. - Late payment. A QR may be paid after it expired —
invoice.paidstill arrives (late: true); credit it. - Refunds. On
invoice.refunded/invoice.partially_refundedsubtract the refunded amount. If the customer already spent it, the balance can go below zero — how to handle that is your decision. - Webhook address: cabinet → Integrations → Webhook.
Limits
- Each pack is one invoice. A paid one counts toward your tariff's monthly limit (Free — 20, Бастау — 800, Бизнес — 4,000 paid payments a month); a pack that was opened but not paid does not count. The daily safety cap counts invoices created that day. On «Бастау», the 80 % monthly-limit notice suggests «Бизнес».
- Each pack is a separate Kaspi payment, and Kaspi charges its fee on each. Packs from 1,000 ₸ make sense; this is not meant for micro-payments (10–100 ₸).
- 2–6 packs per link, label up to 60 characters, one pack at most 5,000,000 ₸.
- One IP may open at most 10 invoices per link per 10 minutes.
Ready-made example
A small Express web app: a "Balance" page, top-up buttons, webhook handling (idempotency, refunds) — https://api.qut.kz/downloads/qutpay-topup-web.zip. README in Kazakh and Russian, offline tests included.
FAQ
Does Qut Pay keep the balance? No. The balance lives in your database. Qut Pay creates the invoice and sends the payment webhook.
Can I sell AI requests in a Telegram bot? Digital goods inside Telegram — Telegram Stars only. Check Telegram's rules for your own case.
What if the customer changes the ref? They top up someone else's balance with their own money. For a strict binding create the invoice on your server with createTopUp.
Can top-ups happen automatically every month? No: the customer confirms every top-up in Kaspi. For regular payments there are subscriptions (an invoice schedule) — the invoice arrives, the customer pays it.
How do I test in sandbox? Create an invoice with a qp_test_… key, then POST /api/v1/invoices/{id}/simulate { "status": "paid" } or press "[Sandbox] төлеу" on the pay page — the webhook is delivered for real.
Need help? WhatsApp +77788813333 · kazprose@gmail.com · 09:00–21:00 (Алматы)
You can also write from the dashboard: Support.
Qut Pay is an independent service, not affiliated with Kaspi Bank JSC. Kaspi and Kaspi Pay are trademarks of their owner.