Add Kaspi payments to your own device via API

If you build a device or write its software yourself — a self-service kiosk, a terminal, a tablet till, an arcade machine, a charging station, anything with a "buy" button — Kaspi payments take one HTTP request. The device asks Qut Pay for an invoice, shows the QR on screen, the customer scans it with Kaspi.kz and pays, the device gets "paid" and dispenses.

Money goes straight to your Kaspi Pay account. Qut Pay never holds funds: it creates invoices, tracks their status and notifies you.

Who it is for

• The device has a screen (or a tablet next to it) and internet.
• You or your developer write the device software, so an HTTP request can be added.
• You have Kaspi Pay registered to a sole proprietorship (ИП) or LLP (ТОО).

Off-the-shelf vending machines without a screen, driven by pulse or MDB (water, coffee, car wash), are better served by vendors of dedicated payment modules: the job there is hardware wired into the machine's board, not an API. Qut Pay sells neither devices nor modules, only a software API.

How it works

Customer presses "Pay"
  → device calls POST /invoices
  → QR on screen (valid ≈3 minutes)
  → customer scans with Kaspi.kz
  → Qut Pay marks the invoice "paid"
  → device gets the result → dispenses

Creating an invoice:

POST https://api.qut.kz/api/v1/invoices
X-API-Key: qp_live_…
Idempotency-Key: kiosk7-000154
{ "amount": 500, "externalOrderId": "kiosk7-000154", "description": "Kiosk #7, 500 ₸" }
→ { "id": "inv_…", "status": "pending", "qrImageUrl": "https://qut.kz/pay/inv_…/qr.svg", "deepLink": "https://kaspi.kz/pay/…", "expiresAt": "…" }

The device renders qrImageUrl (SVG). If scanning a screen is awkward, take the customer's phone number and push the invoice into their Kaspi.kz app instead: "kind": "phone" with customer.phone (whole tenge only).

Knowing the payment went through

Two ways, which can be combined:

1. Webhook. Qut Pay sends a signed (HMAC-SHA256) invoice.paid event to your server. If your devices report to one server, the server tells the device to dispense. This is the most reliable path.

2. Polling. A device behind NAT or on a GSM modem, without a fixed address, cannot receive incoming requests. It then calls GET /invoices/{id} every 2–3 seconds and dispenses once status is paid. After expiresAt it clears the screen and creates a new invoice if needed.

Late payments happen: if the customer scans at the last second, an expired invoice can turn paid shortly after. Your software must handle that — dispense or refund.

Keeping the key safe

• A separate API key per device (cabinet → Integrations). If a device is stolen or tampered with, you revoke only its key; the rest keep working.
• A default key carries only invoices:read and invoices:write — no refunds. Do not give a device the refund scope.
• With many devices reporting to one server, keep the key on the server and let devices talk only to it.
• Send an Idempotency-Key: if the connection drops and the request is retried, no second invoice is created.

Several locations, several cashiers

The cabinet lets you connect several Kaspi cashiers and bind an API key to a specific one. Each location's payments go through its own cashier and reports split by location. Put the device id into externalOrderId and metadata, and every payment tells you which machine it came from.

What is ready

• REST API and OpenAPI: api.qut.kz/docs
• SDKs for Node, PHP and Python; integration guide: api.qut.kz/docs/guide/en/integration
• A ready guide for AI agents — Claude, Cursor or ChatGPT add the payment to your device code themselves: api.qut.kz/for-ai
• Sandbox: a qp_test_… key works without Kaspi and without real money. Pay with POST /invoices/{id}/simulate; webhooks are delivered for real. Test the whole device before connecting a cashier.

Pricing

7 days free, counted from the first live invoice. Then from 4 990 ₸ a month for 800 invoices. The platform takes no percentage of payments; Kaspi charges its own fee (0.95 % for QR) separately, as it would without us. With many devices, pick the plan by invoice count: pricing.

Limits to know up front

• Internet is required. The invoice is created on Kaspi's side; an offline device cannot show a QR.
• A QR is valid ≈3 minutes — Kaspi's limit. If the customer is too slow, a new invoice is created.
• If the Kaspi cashier connection drops (someone signs in to Kaspi Pay with the cashier's number), invoices cannot be created and the API returns kaspi_session_expired. You get a Telegram alert and reconnect in the cabinet. On this error the device should show "Payment temporarily unavailable".
• Qut Pay is an independent service working on top of your own Kaspi Pay account with the "Cashier" role. We are not affiliated with Kaspi Bank JSC. Kaspi-related terms and risks: trust center.

Questions about your device setup — write to Support in the cabinet or via contacts, and we will work out together whether webhook or polling fits.

Updated: 2026-11-02