In short
If you are building a Kazakhstan e-commerce integration from outside the region, Kaspi is the platform you cannot skip. It is the dominant marketplace and payment app in the country, and most local shoppers expect it. The problem for a developer is that the official docs on guide.kaspi.kz are published as scattered question-and-answer pages, largely in Russian, with no single reference you can read front to back. This guide pulls the Kaspi API into one place: what the Merchant API actually does, where the sharp edges are, why there is no stock endpoint, the open-source options, and how payments through Kaspi Pay are a separate system entirely.
First, a terminology split that trips up almost everyone. "Kaspi API" means two unrelated things. One is the Merchant API for the marketplace: orders, products, and prices in your Kaspi.kz shop. The other is Kaspi Pay for accepting money: QR, pay-by-phone, and installments. Different auth, different rules, different contracts. Treat them as two integrations, not one.
Merchant API: auth and request shape
You generate the token in the seller web cabinet under Settings, API Token, Generate. It is a long-lived token, so there is no OAuth refresh loop to build. It goes into the X-Auth-Token header. Two more headers are mandatory: Accept: application/vnd.api+json and Content-Type: application/vnd.api+json. The API follows the JSON:API specification, so responses arrive wrapped in data, attributes, and relationships. If your mental model is flat REST, budget time to unwrap that structure on every call.
Source: the official guide.kaspi.kz Merchant API page, public page captured in July 2026.
One trap the docs never state plainly: Merchant API tokens are permanent, while Kaspi Pay tokens expire after one hour. Do not carry a refresh-token pattern from one into the other. Code written for the hourly Pay token is dead weight in a marketplace integration, and a permanent token simply will not authenticate against Pay.
For a long time there was no sandbox for the Merchant API at all. Teams that integrated in 2023 and 2024 debugged against live orders from real customers, as one integration write-up on Habr describes candidly. Before you ship a method, at least drive it through Postman or Insomnia and confirm you get a 200, not a silent 400 from a forgotten Content-Type header.
Orders: how it behaves in practice
Orders are the main flow. A GET against the order list accepts filters for state, status, creation date, delivery type, and pagination. From an order code you fetch details, line items, and the delivery address. Simple on paper. In practice, one order is not one request.
Assembling a complete order record takes four or more calls: the order itself, its entries, the product codes inside those entries, and the delivery address. JSON:API implies you can pull related resources in one go, but you end up walking relationships by hand. At a few hundred orders a day that adds up, which surfaces the next surprise: rate limits.
The original cap was harsh, around 100 requests per hour, which a shop with real volume hits almost immediately. Kaspi later raised it, but the habit of being frugal with calls is still correct. Cache your reference data, do not poll statuses in a tight loop, and spread synchronization over time. During large sale events, raise your client timeouts to 15 to 20 seconds, because Kaspi responds more slowly under peak load.
Two more field-level gotchas. The status filter can lie: request orders in APPROVED_BY_BANK and you may get back orders sitting in ACCEPTED_BY_MERCHANT, so re-check the status in the response rather than trusting the filter. And the order payload does not carry your internal SKU. The mapping from a Kaspi product code to an item in your own system is yours to maintain.
Products, prices, and the missing stock method
The API handles products and prices: you can add items, update prices, and manage listings. What it does not have is a "set stock level" method. This is not a bug in one version. It is a deliberate design choice, and it breaks the intuition of anyone arriving from Shopify, Amazon, or a typical marketplace API.
Stock and price are ingested through a feed: an XML file at a URL you host, which Kaspi polls once per hour. You cannot set a quantity with a direct API call; you update the feed, and Kaspi picks up the change on the next cycle. That hour of lag creates the classic race condition where your site already shows zero while the marketplace keeps taking orders for an item you no longer have.
Here is how teams cope. When something sells out before the feed refreshes, the only lever left is to cancel the order. But Kaspi polices seller cancellations hard: cross a 5% cancellation rate and penalties kick in. The first violation is a 7-day sales suspension, the second is another 7 days, and a third can end the partnership. So "cancel anything I do not have" is a fast path to a ban. The safer pattern is a stock buffer: pull an item from sale early, at two or three units left rather than at zero, and refresh the feed more often on your side than the hourly poll. One more detail: price and stock travel together in the feed, so you cannot update stock alone without re-sending the price. That shapes how you build the export.
Open source: do not hand-roll the client
If you work in Go, look at abdymazhit/kaspi-merchant-api. It is MIT-licensed with no external dependencies and wraps orders, entries, products, attributes, reviews, points of service, and cities. It covers the marketplace Merchant API, not "all of Kaspi," so treat it as a community implementation of the public surface. Even if Go is not your stack, the README and file layout give you a fast map of the endpoints, and they confirm what is missing: no stock method anywhere in the surface.
The value of a wrapper like this is not the day or two of setup it saves. It encodes the JSON:API response shapes and the edge cases you would otherwise discover the hard way. Unwrapping data.attributes.relationships by hand on every endpoint is tedious and error-prone, and a ready client removes that grind. Just do not treat it as a black box. Kaspi changes fields without loud announcements, so the layer between you and the API will still need maintenance now and then.
Kaspi Pay: a separate system for money
The Merchant API is about orders. Taking money is Kaspi Pay, and it works differently. A direct webpay partnership with Kaspi gives you acquiring, QR, and pay-by-phone, but it requires a bank contract, a local business ID, a settlement account at a Kazakhstan bank, and verification. For a large merchant that is the normal route. For a smaller project that just needs to accept a payment on a site next week, the barrier is high.
A layer of intermediary services has grown up around this, offering a REST wrapper over Kaspi Pay: issue an invoice by phone number, receive a webhook on payment, return a fiscal receipt. The better-known ones include apipay.kz, aipay.kz, and kpayapp.kz, the last of which can trigger a payment straight from a local CRM. Treat them as a separate contract layer: verify pricing, fees, settlement timing, webhook reliability, and legal model before production traffic depends on them.
An important market boundary: Kaspi Pay works with cards and accounts of Kazakhstan residents. If your buyers include people abroad, Kaspi Pay alone will not cover them. You will need a separate international gateway, such as Stripe, alongside it. Design for that split up front rather than when your first foreign customer hits the payment form.
Wiring Kaspi into the rest of the stack
In a real shop, the Kaspi API rarely lives alone. It hangs off an inventory or accounting system, and off a CRM. The shape is consistent: orders from Kaspi land in your system, stock and prices export from your system into the feed, and statuses sync both ways. In the CIS market this back office is often a local ledger platform rather than the Western tools you would reach for elsewhere, which is one reason ready-made Kazakhstan connectors exist for the common cases. If your case is standard, an off-the-shelf connector will handle it.
Custom work starts where the standard export breaks. Multiple Kaspi cabinets under one legal entity, warehouses with different reservation logic, your own rules for pulling items from sale, low-stock alerts to a manager, and mapping Kaspi codes to internal SKUs all defeat boxed connectors. That is where integration development for Kazakhstan pays off: a careful layer between Kaspi, your back office, and your messaging channels that respects the hourly feed, the cancellation cap, and the lying status filter.
If you want automation on top of the order data, say a bot that answers a buyer about order status or warns a manager that an item is about to sell out, that is a GPT integration over the Kaspi API. In our SellerBox AI work we connected marketplace data to a conversational layer for sellers, and most of the effort went not into the model but into taming exactly these API quirks.
How to start the integration
Do not try to conquer the whole Kaspi API at once. A sane order: first the token and a single GET on the order list, just to see the JSON:API shape for real. Then assembling a full order record across its four-plus calls and mapping codes to your products. Then exporting the price-and-stock feed and confirming Kaspi ingests it. Only when that is stable do you add statuses, cancellations under the 5% cap, and two-way sync.
Run Kaspi Pay as a separate track, never mixed into the Merchant API. Decide early: a direct acquiring contract or an intermediary service. That choice drives your complexity, your timeline, and who owns fiscalization.
If your shop is already losing orders to the hourly feed lag or catching suspensions for cancellations, start with one narrow bottleneck. The fastest win is usually not "rewrite the whole integration" but adding a stock buffer and a proper feed sync. If you want that layer built for your specific back office and shop rules, talk to us about a Kazakhstan integration and we will work through your actual cabinet.
FAQ
Where do I get a Kaspi Merchant API token?
In the seller web cabinet under Settings, API Token, Generate. The token is permanent, so there is no scheduled refresh. It goes in the X-Auth-Token header. Do not confuse it with Kaspi Pay tokens, which expire after an hour.
Why is there no stock endpoint in the Kaspi API?
By design. Kaspi ingests stock and price from a feed, an XML file it polls once per hour, rather than through a direct call. You cannot set a quantity on demand, so shops keep a buffer and pull items from sale before they hit zero.
Can I just cancel orders when an item is out of stock?
Technically yes, but carefully. Kaspi caps seller cancellations: cross 5% and you get a 7-day sales suspension, with repeats escalating to termination of the partnership. It is better not to let stock reach zero than to cancel after the fact.
How is Kaspi Pay different from the Merchant API?
The Merchant API covers orders, products, and prices on the marketplace. Kaspi Pay covers taking money: QR, pay-by-phone, and installments. Different auth, rules, and contracts. They are commonly confused but must be integrated as two separate systems.
Are there ready-made Kaspi API libraries?
Yes. For Go there is the open-source abdymazhit/kaspi-merchant-api (MIT), covering orders, products, attributes, and reference data in the Merchant API. For payments, intermediary services such as apipay.kz, aipay.kz, and kpayapp.kz offer a REST wrapper over Kaspi Pay.