Qut PayСайтКабинетБаза знанийAPI (OpenAPI)Инструкция для ИИРУСҚАЗ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 в ссылке, он лишь пополнит чужой баланс своими деньгами — забрать чужие деньги так нельзя. Если нужна жёсткая привязка (например, клиент не должен видеть свой 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']);

Без SDK: POST /api/v1/invoices с телом { "amount": 5000, "kind": "qr", "description": "Пополнение баланса", "metadata": { "ref": "user_42", "pack": "pro-600", "qutpay_kind": "topup" } }. В MCP — инструмент qutpay_create_topup. В n8n — workflow qutpay-create-topup.json.

Обработка 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 — товарные знаки правообладателя.