← qut.kz

Kaspi Pay API for websites and apps

Kaspi does not publish an open Kaspi Pay API that any shop can plug into from documentation. Qut Pay gives developers a plain REST API on top of your own Kaspi Pay: your server creates an invoice with one request, the buyer pays by Kaspi QR, by an invoice pushed to the Kaspi.kz app on their phone number, or by link, and your server receives a signed invoice.paid webhook. It works through the "Cashier" role of your Kaspi Pay business account. Money goes straight to your Kaspi Pay account; Qut Pay never touches it.

This page is a reference for developers adding Kaspi payments to an online store, SaaS, mobile app, bot or CRM. Connecting the cashier is a one-time setup described in the getting-started guide.

The API at a glance

It is a Kaspi payments API for businesses in Kazakhstan: amounts are in tenge, KZT only.

Your site talks to Qut Pay at two points only: it creates an invoice and it learns the result.

Your server ──POST /api/v1/invoices──▶ Qut Pay ──invoice──▶ Kaspi
   ◀── payUrl, qrImageUrl, deepLink
buyer pays in Kaspi.kz
   ◀── POST to your endpoint: invoice.paid (HMAC-SHA256)

Create an invoice

Only one field is required: amount, in tenge.

curl -X POST https://api.qut.kz/api/v1/invoices \
  -H 'X-API-Key: qp_test_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1001-pay' \
  -d '{
    "amount": 2500,
    "description": "Order #1001",
    "externalOrderId": "1001",
    "successUrl": "https://site.kz/ok",
    "metadata": { "branch": "almaty-1" }
  }'

Response — HTTP 201:

{ "id": "inv_…", "status": "pending", "payUrl": "https://qut.kz/pay/inv_…", "qrUrl": "…", "deepLink": "…", "qrImageUrl": "…", "expiresAt": "…" }

Send the buyer to payUrl, or render the QR on your own page. Every request and response field and the error codes are in the integration guide and the OpenAPI reference.

There is no separate Kaspi QR API to look for: one endpoint covers all three cases, and the kind field picks the type.

MethodIn the APIBest for
Kaspi QRkind: "qr" (default), image qrImageUrl (SVG) or qrPngUrlWebsite, kiosk screen, shop window
Invoice to the buyer's numberkind: "phone" with customer.phone as 7XXXXXXXXXXSelling in chat or by phone, subscriptions
Payment linkpayUrl is a ready payment page, deepLink opens the Kaspi app directlyA link in a messenger, a redirect from your site

Payment webhooks and signature checks

Add the endpoint in the cabinet under Integrations: you pick the events there, and the secret is shown once. In live mode the endpoint must be https on a real domain and must not sit behind a password.

POST /qutpay-webhook
X-Webhook-Event: invoice.paid
X-Webhook-Timestamp: 1757167000
X-Webhook-Signature: sha256=3f1a…
X-Webhook-Delivery: 17

{ "event": "invoice.paid", "invoice": { "id": "inv_…", "externalOrderId": "1001", "status": "paid", "amount": 2500, "metadata": { "branch": "almaty-1" }, "paidAt": "…" }, "sentAt": "…" }

The signature is computed as:

signature = "sha256=" + hex( HMAC-SHA256( secret, timestamp + "." + rawBody ) )

Four rules:

  1. Compute the signature over the raw request body, before parsing JSON. After JSON.stringify(req.body) the bytes differ and the signature never matches.
  2. Reject a timestamp older than 5 minutes. Compare signatures in constant time: timingSafeEqual, hash_equals, hmac.compare_digest.
  3. Answer 2xx first, do the work afterwards. On a non-2xx answer the delivery is retried up to 11 times, with the pause growing from 10 seconds to an hour.
  4. Handle each event once per (invoice.id, status) pair: the same event can arrive more than once.

Two events are usually enough: invoice.paid and invoice.refunded. If money for an already closed invoice (expired, cancelled) arrives late, invoice.paid still comes, flagged late: true: fulfil the order or refund it.

Polling instead of webhooks

If your system has no address reachable from outside (a device behind NAT or on a GSM modem, a bot builder), ask for the status yourself:

GET https://api.qut.kz/api/v1/invoices/{id}
X-API-Key: qp_live_…
→ { "id": "inv_…", "status": "paid", … }

When the buyer is waiting in front of a screen, run both channels. The webhook stays the main one and usually arrives within 5 seconds; for the first 30 seconds also poll the status about once a second. Whichever comes first wins. For kiosks and terminals there is a separate page: Kaspi payments for your own device via API.

Refunds, idempotency, metadata

Refund — POST /api/v1/invoices/{id}/refund with { "amount": 1500, "reason": "Item returned" }. Without amount the invoice is refunded in full; with it, partially (status partially_refunded), and the refunds together cannot exceed the amount paid. The key needs the refunds:write scope, and the money leaves your Kaspi account. On refund_unknown or refund_pending_unknown do not retry: read the invoice status.

Idempotency-Key — a header whose value your system derives, for example order-1001-pay. A retry with the same key creates no new invoice: you get the original back with HTTP 200 and idempotentReplay: true. So retrying after a timeout is safe.

externalOrderId — your order number. It comes back in the webhook and lets you find the invoice: GET /api/v1/invoices?externalOrderId=1001. It does not stop duplicates; that is what Idempotency-Key is for.

metadata — any JSON: point of sale, cart, locker number. Stored unchanged and returned both in the webhook and in the status response.

Sandbox, keys, rate limits

SDKs, plugins and tools

A Node.js SDK example: create an invoice and accept the webhook.

import express from 'express';
import { QutPay, verifyWebhook } from '@qutpay/sdk';

const app = express();
const qp = new QutPay({ apiKey: process.env.QUTPAY_API_KEY });

app.post('/buy', async (req, res) => {
  const inv = await qp.createInvoice({
    amount: 2500,
    description: 'Order #1001',
    externalOrderId: '1001',
    successUrl: 'https://site.kz/ok',
    idempotencyKey: 'order-1001-pay', // sent as the Idempotency-Key header
  });
  res.redirect(inv.payUrl);
});

app.post('/qutpay-webhook', express.raw({ type: '*/*' }), (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 (event === 'invoice.paid') markPaid(invoice.externalOrderId);
  res.sendStatus(200);
});
WhatWhere to get it
Node.js SDK: @qutpay/sdk, ESM, Node.js 18+, no dependenciesqutpay-sdk-node.zip
PHP SDK: a single file, PHP 7.4+, classes \QutPay\Client and \QutPay\Webhookqutpay-sdk-php.zip
Python SDK: standard library only, Python 3.8+, create_invoice and verify_webhookqutpay-sdk-python.zip
WooCommerceplugin on WordPress.org · guide
OpenCart 4qutpay.ocmod.zip
n8n: ready workflows that create an invoice and receive events with signature checksqutpay-n8n.zip
1C1C integration (in Russian)
MCP server for AI agents (Claude Code, Cursor, Claude Desktop): invoices, status, refunds, sandbox payment simulationnpx -y @qutpay/mcp or remote https://api.qut.kz/mcp · guide
A guide for AI assistants: Claude, Cursor or ChatGPT write the integration themselvesapi.qut.kz/for-ai · SKILL.md · llms.txt

No code of your own is needed either: Tilda forms connect through a form hook (cabinet → Integrations), and a Salebot bot issues the invoice in one block — Salebot + Kaspi invoices.

Mobile apps

The app never calls Qut Pay directly, only through your server:

App → Your server → Qut Pay → Kaspi

A key inside an APK or IPA can be extracted, so the key stays on the server. The server creates the invoice and hands the app payUrl or deepLink, which opens Kaspi on the phone right away; the server learns about the payment from the webhook and tells the app.

What you need and what it costs

More: pricing (in Russian), Kaspi payment services compared, with prices and sources (in Russian).

Limits to know up front

Frequently asked questions

Does Kaspi have an official API for websites?

Kaspi has no public payment-acceptance API that any business can connect from documentation. Officially there is the Kaspi Pay app and individual integrations under a contract with Kaspi. Qut Pay provides a REST API on top of the "Cashier" role in your own Kaspi Pay account. It is an independent service, not a Kaspi partner.

Does the money pass through Qut Pay?

No. The invoice is issued on behalf of your cashier, and the buyer pays straight into your Kaspi Pay business account. Refunds are also made by Kaspi from your account. The platform has no access to your funds.

How do I test without a cashier or real money?

With a qp_test_… key in the sandbox. Create an invoice, call POST /api/v1/invoices/{id}/simulate with status paid, and a real signed webhook reaches your endpoint. In the sandbox the endpoint can be http://localhost. Once everything works, connect the cashier and switch to a qp_live_… key.

Can I call the API straight from the browser or a mobile app?

No. Anyone can pull a key out of browser JavaScript or an APK/IPA and issue invoices in your name. The browser and the app talk to your server, and the server talks to Qut Pay.

What happens if I retry the create-invoice request?

With the same Idempotency-Key header you get the invoice that was already created (HTTP 200, idempotentReplay: true), and no second one appears. Without that header every request creates a new invoice, even with the same externalOrderId.

Do I give Qut Pay my Kaspi Pay password?

No. The cashier is connected with an SMS code sent to the cashier's number. The password is neither requested nor stored.

Related (in Russian): Kaspi invoice by phone number with a webhook, Kaspi and 1C, Kaspi payments in Telegram bots and WhatsApp, comparison of Kaspi payment services.

Start with a sandbox key

Sign up, create a qp_test_… key and run the whole flow in the sandbox — no cashier, no real money.

Sign up API docs

Qut Pay is an independent service, not a Kaspi partner and not affiliated with Kaspi Bank JSC. You need a Kaspi Pay business account (sole proprietor or LLP). More: getting started, pricing, trust center, contacts.

Updated: 2026-11-22