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.
- Base URL:
https://api.qut.kz/api/v1, JSON, HTTPS only. - Key in the
X-API-Keyheader (orAuthorization: Bearer …):qp_test_…for the sandbox,qp_live_…for real payments. - Invoices: create, read status, list, cancel, refund; up to 100 invoices in one request (
POST /api/v1/invoices/bulk). - Result: an HMAC-SHA256 signed webhook, or a
GET /api/v1/invoices/{id}request. - Spec: OpenAPI JSON, reference at api.qut.kz/docs, guide: Website integration (API).
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.
Kaspi QR, an invoice to a phone, or a link
There is no separate Kaspi QR API to look for: one endpoint covers all three cases, and the kind field picks the type.
| Method | In the API | Best for |
|---|---|---|
| Kaspi QR | kind: "qr" (default), image qrImageUrl (SVG) or qrPngUrl | Website, kiosk screen, shop window |
| Invoice to the buyer's number | kind: "phone" with customer.phone as 7XXXXXXXXXX | Selling in chat or by phone, subscriptions |
| Payment link | payUrl is a ready payment page, deepLink opens the Kaspi app directly | A link in a messenger, a redirect from your site |
- The QR scanning window is about three minutes, set by Kaspi. Do not hard-code it; read
expiresAtfrom the response. - A phone invoice takes whole tenge only and a description of up to 60 characters (100 for QR). If the number is not a Kaspi customer, you get
422 kaspi_customer_not_found: do not retry, offer a QR instead. - A permanent link not tied to an order (Instagram, a printed QR, balance top-up packs):
POST /api/v1/payment-linkscreates aqut.kz/p/<slug>page. Each payment through it is an ordinary invoice with the same webhooks.
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:
- Compute the signature over the raw request body, before parsing JSON. After
JSON.stringify(req.body)the bytes differ and the signature never matches. - Reject a
timestampolder than 5 minutes. Compare signatures in constant time:timingSafeEqual,hash_equals,hmac.compare_digest. - 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.
- 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
- Sandbox. A
qp_test_…key works without a cashier and without real money; Kaspi is never called.POST /api/v1/invoices/{id}/simulatewith{"status":"paid"}(orfailed,expired) imitates the payment. Webhooks are delivered for real, and the endpoint may behttpandlocalhost. Sandbox invoices do not count toward the plan's limit and do not start the trial. - Keys. Created in the cabinet (Integrations → API keys) and shown once. A key lives on the server only. Use a separate key per integration. By default a key has
invoices:readandinvoices:write; refunds need the separaterefunds:writescope. With several locations or projects, a key can be bound to a specific cashier. - Rate limits. Per key: 600 reads (GET) and 200 writes a minute. Above that you get
429 request_rate_limitedwith aRetry-Afterheader;X-RateLimit-Remainingshows what is left. The codestariff_limit_reachedandtariff_daily_burstalso come with HTTP 429, but they are plan limits, and retrying will not help.
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);
});
| What | Where to get it |
|---|---|
Node.js SDK: @qutpay/sdk, ESM, Node.js 18+, no dependencies | qutpay-sdk-node.zip |
PHP SDK: a single file, PHP 7.4+, classes \QutPay\Client and \QutPay\Webhook | qutpay-sdk-php.zip |
Python SDK: standard library only, Python 3.8+, create_invoice and verify_webhook | qutpay-sdk-python.zip |
| WooCommerce | plugin on WordPress.org · guide |
| OpenCart 4 | qutpay.ocmod.zip |
| n8n: ready workflows that create an invoice and receive events with signature checks | qutpay-n8n.zip |
| 1C | 1C integration (in Russian) |
| MCP server for AI agents (Claude Code, Cursor, Claude Desktop): invoices, status, refunds, sandbox payment simulation | npx -y @qutpay/mcp or remote https://api.qut.kz/mcp · guide |
| A guide for AI assistants: Claude, Cursor or ChatGPT write the integration themselves | api.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
- A Kaspi Pay business account registered to a sole proprietorship (ИП) or LLP (ТОО).
- A separate number for the cashier that holds only the "Cashier" role — see the getting-started guide.
- A 7-day trial, counted from the first live invoice. After that a free plan remains — 20 payments a month; for more, from 4 990 ₸ a month for 800 payments. Only paid invoices count toward the limit. The API, webhooks, refunds, SDKs and plugins are on every plan.
- The platform takes no percentage of payments; Kaspi charges its own fee (0.95 % for QR) separately, as it would without us.
More: pricing (in Russian), Kaspi payment services compared, with prices and sources (in Russian).
Limits to know up front
- Qut Pay is an independent service, not a Kaspi partner, and not affiliated with Kaspi Bank JSC. It works through the standard "Cashier" role of your business account. Kaspi has no public API for third-party services and may restrict such access, or a cashier with an abnormally large flow. Money already received on your account is unaffected.
- If the cashier connection drops (for example, someone signs in to Kaspi Pay with the cashier's number), no new invoices can be created and the API returns
409 kaspi_session_expired. You get a Telegram alert and reconnect the cashier in the cabinet. Handle this code: show "Payment temporarily unavailable" or offer another way to pay. - Internet is required: the invoice is created on Kaspi's side.
- There is no contractual SLA. Status, security measures and risks are in the trust center.
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.
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.