A step-by-step guide: create a Kaspi Pay cashier, connect a cash register, get an API v2 key, set up a webhook, and test everything in the sandbox. For a website, bot, CRM, or no code at all.
This is an overview route for connecting xpayment to Kaspi Pay: from an empty account to your first payment. It helps you see the order of the steps and not get lost. Detailed instructions live in separate articles, linked from each step.
Kaspi Pay is the provider that is supported today; other payment systems will follow. Buyers’ money goes straight to your Kaspi account: xpayment does not hold it.
After you connect a cash register (steps 1–2 below), you choose how to accept payments:
| Way | Who it is for | What you need |
|---|---|---|
| No code | A shop, studio, tutor, or service without a developer | Create a payment link or online booking in the dashboard and send the link to the customer. More: Accept payments without coding |
| Through API v2 | A website, Telegram bot, CRM, app, or SaaS | An xapi_… key, a POST /v2/payments/link or POST /v2/payments request, and a webhook |
You need the register either way; the key and the webhook are only needed when you work through the API.
| What | Why |
|---|---|
| An individual entrepreneur (ИП) or a company (ТОО) and a Kaspi Pay account | The register takes money to a business account, not a personal card |
| A smartphone with the Kaspi Pay app | For the owner and for the cashier |
| A separate phone number | For the restricted cashier role. It cannot belong to the owner of another Kaspi Pay account |
| A way to sign in to xpayment | Through Google or with a password |
| A public HTTPS webhook URL | Only for the API: so your system receives payment statuses |
Kassa1.xapi_…. One key works with all your registers, and it keeps working if a register has to be reconnected.You start with 3 free days of trial access, enough to check the API, QR, deeplink, and phone invoices. Then you choose a fixed tariff by payment volume: “Старт” (Start) — 10 000 ₸/month (up to 250 payments a month), “Рост” (Growth) — 25 000 ₸/month (up to 2 000 payments), or “Масштаб” (Scale) — 60 000 ₸/month (no limit on payments). If a fixed tariff does not fit, you can pick the percentage model of 1–4%. You can estimate the commission in the calculator.
First prepare the Kaspi Pay side: make sure the business account is active and create a separate cashier with restricted rights. We do not repeat the full screen-by-screen instructions here; they are in a separate article: How to add a Kaspi Pay cashier for online payments.
Before moving to xpayment, make sure that:
xpayment does not work with the owner’s main account. We understand that handing access to a third-party service is scary, so the secure model is built around the Cashier role: it is restricted and exists only for accepting payments.
| A cashier can | A cashier cannot |
|---|---|
| Accept payments | Transfer money |
| See their own operation history | Access the full business account |
| See other cashiers’ operations |
Even if a cashier’s data fell into the wrong hands, this role cannot harm the business. It is the minimum access that is enough for accepting payments.
Official Kaspi materials:
Services -> Company profile -> Employees -> Add, role “Cashier” (in the Russian app: Сервисы -> Профиль компании -> Сотрудники).If you need this stage in detail, open the separate article about the cashier and go through it fully, then come back to step 2.
Now that the cashier is ready in Kaspi Pay, move to xpayment. A “cash register” in the dashboard is simply a connected Kaspi Pay cashier: xpayment issues invoices and checks payments through it.
Open Кассы и счета (Cash registers and accounts) and select Подключить кассу (Connect a cash register). The wizard has three steps:
Kassa1. You will use this name to choose the register in API v2 requests;The cashier’s phone must be at hand when you confirm.
Sometimes Kaspi stops accepting the register’s session, and the dashboard marks it as not working. Connect the register again and give it the same API name. You will not have to change your code or your xapi_… key.
Details about the wizard, errors, and checking: Connecting a cash register and getting an API v2 key. What exactly you create and why: How the xpayment virtual cashier works.
The register is connected, but no key is issued automatically: you create it yourself. The key is how your server proves that requests come from you.
xapi_ and survive reconnecting a register.Rules for handling the key:
Register keys
xdev_…(the “Ключи касс (v1)” block) belong to API v1. It is still supported, but use API v2 for new integrations.
Create a 1 500 ₸ payment link through the register Kassa1:
curl -X POST https://api.xpayment.kz/v2/payments/link \
-H "Authorization: Bearer xapi_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"device_name": "Kassa1", "amount": 1500, "merchant_order_id": "order-42"}'
The response contains payment_id, qr_token (the address for a QR code or deeplink), qr_operation_id, and expire_date. Show qr_token as a QR code or a link, and the buyer pays in the Kaspi app.
Want to try it first without real money? The same requests work in the sandbox with a test key xapi_test_….
A webhook is a request that xpayment sends to your server when a payment changes status. Thanks to it you do not have to keep asking the API whether the customer has paid: the order is confirmed automatically.
https://example.com/webhook.payment.completed, payment.cancelled, payment.expired, and payment.failed are enough. If you make refunds, add payment.refunded and payment.refund_failed.openssl rand -hex 32). Every request is signed with it, so do not leave the field empty.GET /v2/payments/{payment_id}.X-xPayment-Signature before processing: Verifying the webhook signature.2xx within 10 seconds. There are three attempts in total: immediately, after a minute, and after 5 minutes.A full breakdown of events, retries, and idempotent processing: xpayment webhooks.
You have a key and a working register. What you do next depends on how you want to accept payments.
If there is no developer, you need neither a key nor a webhook. In the dashboard, create a payment link, online booking, or recurring payments and send the link to the customer on WhatsApp, Instagram, or Telegram. The customer pays in Kaspi, and you see the list of payments in the dashboard. More: Accept payments without coding.
If you work on an xpayment partner platform (for example, tec.delivery), it is simple:
After that, online payments through Kaspi Pay will work in your business automatically. The list of partner platforms will keep growing.
If you are a developer or your service supports direct API connections, work with xpayment directly.
FAILED is not a final status.Open the API documentation page: it is interactive, so you can paste your key and send a request right from the browser.
xapi_… key into the Bearer token field.POST /payments/link, press “Try it”, fill in device_name and amount, and send the request.API v1 with a register key
xdev_…is still supported, but we recommend v2 for new integrations.
You have gone from zero to a working integration:
Now you can accept Kaspi Pay payments without acquiring applications and without weeks of approvals. The first 3 days are free; after that you choose a fixed tariff or the percentage model: see “Тариф и баланс” (Tariff and balance) in the dashboard and the calculator.
If something goes wrong, look at the other articles in this section or contact support.