Full Onboarding Guide: From Kaspi to Your First Payment

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.

Welcome to xpayment

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.

Two ways to accept payments

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 the connection looks like

  1. Prepare Kaspi Pay and add a cashier
  2. Connect the cash register in xpayment
  3. Create an API v2 key and make your first request
  4. Set up a webhook (for the API): xpayment webhooks
  5. Test everything in the sandbox with no real money: Sandbox
  6. Choose a payment flow: compare first — QR, deeplink, or remote phone payment — then implement: POST /v2/payments or POST /v2/payments/link

What you will need

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

What you get in the end

  1. A restricted Kaspi Pay cashier instead of access to the owner’s main account. A cashier can accept payments and see only their own operations. They cannot transfer money or see the company balance.
  2. A cash register in xpayment with a clear API name, for example Kassa1.
  3. An API v2 key xapi_…. One key works with all your registers, and it keeps working if a register has to be reconnected.
  4. Signed webhooks: automatic payment notifications.
  5. A way to accept payments for a website, bot, CRM, SaaS, or n8n.

How much it costs

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.

Step 1. Prepare Kaspi Pay

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.

What to check in Kaspi Pay

Before moving to xpayment, make sure that:

  1. You have an ИП or ТОО and an active Kaspi Pay business account, and you are its owner.
  2. A point of sale exists in Kaspi Pay.
  3. You have a separate phone number for the cashier. It must not belong to the owner of another Kaspi Pay account.
  4. The cashier can sign in to the Kaspi Pay app by SMS link.

Why we use a cashier

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:

What to do now

  1. If Kaspi Pay is not connected yet, activate the business account in the Kaspi Pay app.
  2. Add a cashier: Services -> Company profile -> Employees -> Add, role “Cashier” (in the Russian app: Сервисы -> Профиль компании -> Сотрудники).
  3. Attach the cashier to the right point of sale.
  4. Save the cashier’s number: you will need it in the next step.

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.

Step 2. Connect the cash register in xpayment

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.

Signing in

  1. Open xpayment.kz and select Войти через Google (Sign in with Google). You can also sign in with a password.
  2. Accept the terms if the dashboard asks you to.

The “Connect a cash register” wizard

Open Кассы и счета (Cash registers and accounts) and select Подключить кассу (Connect a cash register). The wizard has three steps:

  1. Check that everything is ready. Tick three items: you have an ИП or ТОО, you are the owner of the Kaspi Pay account, and you added a separate number as a cashier.
  2. The cashier’s number. Fill in three fields:
    • Название кассы (Register name): any clear name, for example “Reception desk”;
    • Имя для API (API name): Latin letters and digits, up to 32 characters, for example Kassa1. You will use this name to choose the register in API v2 requests;
    • The number added as a cashier in Kaspi Pay: an SMS with a code will be sent to it. The Kaspi Pay owner’s number will not work.
  3. The SMS code. Enter the code and confirm. The register is connected.

The cashier’s phone must be at hand when you confirm.

If the register has to be reconnected

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.

Step 3. The API v2 key and your first request

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.

Creating a key

  1. Open API-ключи (API keys) and find the Ключи API v2 (API v2 keys) block. These are the recommended keys: they start with xapi_ and survive reconnecting a register.
  2. Create a key and give it a name, for example “Website” or “CRM”.
  3. Copy the key right away: it is shown once; afterwards xpayment keeps only its SHA-256 hash and cannot restore the value.

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.

The first request

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_….

Step 4. The webhook

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.

How to create one

  1. Open Вебхуки (Webhooks) and select + Новый вебхук (New webhook).
  2. Enter the HTTPS address of your handler, for example https://example.com/webhook.
  3. Choose the events. For most projects payment.completed, payment.cancelled, payment.expired, and payment.failed are enough. If you make refunds, add payment.refunded and payment.refund_failed.
  4. Set a Secret: a long random string (openssl rand -hex 32). Every request is signed with it, so do not leave the field empty.
  5. Save, and press Тест (Test) to check the connection.

What to know right away

A full breakdown of events, retries, and idempotent processing: xpayment webhooks.

Step 5. Connect it to your platform

You have a key and a working register. What you do next depends on how you want to accept payments.


Option A — no code

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.


Option B — partner platforms (for example, tec.delivery)

If you work on an xpayment partner platform (for example, tec.delivery), it is simple:

  1. Sign in to your account on the platform.
  2. Go to the company settings.
  3. Find the section related to payments or xPayment.
  4. Paste an API key from the API-ключи (API keys) section into the field. The platform itself tells you next to the field which type of key it needs.
  5. Save the settings.

After that, online payments through Kaspi Pay will work in your business automatically. The list of partner platforms will keep growing.


Option C — REST API v2

If you are a developer or your service supports direct API connections, work with xpayment directly.

  1. Choose a flow: QR, deeplink, or remote phone payment.
  2. Implement it:
  3. Confirm payments with webhooks, not by polling.
  4. Learn the payment statuses and refunds: in xpayment FAILED is not a final status.
  5. If you run a SaaS with plans, see the subscriptions API.

Open the API documentation page: it is interactive, so you can paste your key and send a request right from the browser.

  1. Open xpayment.kz/docs and pick the “API v2” section.
  2. Paste your xapi_… key into the Bearer token field.
  3. Choose an endpoint, for example 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.


Done

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.