The "Connect a cash register" wizard step by step: the API name (device_name), the SMS code, creating an xapi_… key, and checking the connection with GET /v2/devices.
A cash register in xpayment is a connected Kaspi Pay cashier. xpayment issues invoices, creates payment links, and checks payments through it. In the dashboard it is called a cash register («Кассы и счета»), in API v2 you choose it by device_name, and in API v1 and internal names the same entity is called a device.
| What you need | Why |
|---|---|
| An ИП or ТОО and a Kaspi Pay account | The register takes money to a business account. You must be its owner |
| A cashier in Kaspi Pay | A separate phone number. It must not belong to the owner of another Kaspi Pay account. Guide: How to add a cashier |
| The cashier’s phone at hand | An SMS with a code will arrive on it |
| An xpayment account | Sign in with Google or a password |
| Room on your tariff | The number of registers is limited by the tariff. If the limit is reached, the wizard suggests changing the tariff («Тариф и баланс») |
Cashier's number -> SMS code from Kaspi -> register in xpayment -> API v2 key (xapi_…) -> your requests
xapi_… key and address the register by its name.For the big picture and the benefits of API v2, see How the xpayment virtual cashier works.
A three-step wizard connects the register. Open Кассы и счета (Cash registers and accounts) and select Подключить кассу (Connect a cash register).
The wizard asks you to tick three items. Most often a connection fails because of one of them:
| Item | Explanation |
|---|---|
| I have an ИП or ТОО | The register takes money to a business account, not a personal card |
| I am the owner of the Kaspi Pay account | Sign in through the Kaspi Pay app or pay.kaspi.kz |
| I added a separate number as a cashier | The cashier’s number cannot belong to the owner of another Kaspi Pay account |
There is also a link to Kaspi’s instructions: “How to add a cashier”. When all items are ticked, select Продолжить (Continue).
Fill in three fields:
| Field | Description | Example |
|---|---|---|
| Название кассы (Register name) | A clear name for you, shown in the dashboard | Reception desk |
| Имя для API (API name) | The name used to choose the register in API v2. Latin letters and digits, 1 to 32 characters | Kassa1 |
| The number added as a cashier in Kaspi Pay | An SMS with a code will be sent to it | +7 700 123 45 67 |
Rules for the API name:
^[A-Za-z0-9]{1,32}$);Kassa1 and kassa1 are the same); a clash gives the error DEVICE_NAME_TAKEN;PUT /v1/devices/{deviceID}), but then update the requests that use the old name.Request the code. If it does not arrive, check that the number really is added as a cashier in Kaspi Pay and does not belong to the owner.
Behind the scenes:
Enter the code from the SMS (Kaspi currently sends 4 digits) and confirm.
Behind the scenes:
If the code is wrong or expired (error CHALLENGE_EXPIRED), go back to step 2 and request a new code. A code that was already used returns CHALLENGE_ALREADY_USED.
No key is issued at this point. The register is ready, but you create the API key yourself, which is the next step.
xapi_….xapi_a1b2c3d4e5f6… (xapi_ + 64 characters)
Copy the key right away. It is shown only once. xpayment stores only a SHA-256 hash and cannot restore the key. If you lose it, revoke the key and create a new one.
What to do with the key:
.env) or in a secret manager.Request the list of your registers:
curl https://api.xpayment.kz/v2/devices \
-H "Authorization: Bearer xapi_YOUR_KEY"
For every active register the response has device_name, name, and session_problem_since: the time since which Kaspi stopped accepting the register’s session. If it is null, the register works.
Use the Подключить заново (Reconnect) action in the register list or on the register’s page:
The main thing: connect the new register with the same API name, and requests with device_name: "Kassa1" keep working without changing the code or the xapi_… key. If the name is still held by another active register, you get the error DEVICE_NAME_TAKEN.
In API v1 an
xdev_…key is tied to a specific register: after the register is deleted such keys stop working, and v1 needs a new key. This is one of the reasons we recommend v2.
The register is connected and you have the xapi_… key. Now connect it to your backend.
All API v2 requests go to https://api.xpayment.kz/v2 with the header Authorization: Bearer xapi_…. You name the register in the request body by device_name:
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"}'
Response 200:
{
"payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
"qr_token": "https://qr.kaspi.kz/553080826307468991696...",
"qr_operation_id": 14893934009,
"ext_tran_id": "QR14893934009",
"status": "QrTokenCreated",
"expire_date": "2026-11-08T16:39:53.000+05:00",
"environment": "live"
}
Show qr_token as a QR code or a button, and wait for the result in the webhook.
Keep the key in an environment variable and never send it to the browser.
const API = "https://api.xpayment.kz/v2"
async function createPaymentLink({ amount, orderId }) {
const res = await fetch(`${API}/payments/link`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.XPAYMENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
device_name: process.env.XPAYMENT_DEVICE_NAME, // for example, Kassa1
amount,
merchant_order_id: orderId,
}),
})
if (!res.ok) throw new Error(`xpayment ${res.status}: ${await res.text()}`)
return res.json() // { payment_id, qr_token, expire_date, ... }
}
import os
import httpx
API = "https://api.xpayment.kz/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['XPAYMENT_API_KEY']}"}
def create_payment_link(amount: float, order_id: str) -> dict:
resp = httpx.post(
f"{API}/payments/link",
headers=HEADERS,
json={
"device_name": os.environ["XPAYMENT_DEVICE_NAME"],
"amount": amount,
"merchant_order_id": order_id,
},
timeout=15,
)
resp.raise_for_status()
return resp.json()
<?php
function createPaymentLink(float $amount, string $orderId): array
{
$ch = curl_init('https://api.xpayment.kz/v2/payments/link');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XPAYMENT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'device_name' => getenv('XPAYMENT_DEVICE_NAME'),
'amount' => $amount,
'merchant_order_id' => $orderId,
]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
throw new RuntimeException("xpayment $status: $body");
}
return json_decode($body, true);
}
device_name in settings, not in code: it makes switching between the live and the test register easy.POST /v2/payments, send X-Idempotency-Key so a repeated request does not create a duplicate.payment.completed.xapi_test_… key and the register test: Sandbox.| HTTP | Code | What to do |
|---|---|---|
| 400 | VALIDATION_ERROR |
Check device_name (Latin letters and digits), amount (> 0), and payer_phone |
| 401 | — | The key is missing, revoked, or of another type. xapi_ works only on /v2, xdev_ only on /v1 |
| 404 | DEVICE_NOT_FOUND |
You have no active register with this device_name |
| 422 | KASPI_ERROR, DEVICE_INACTIVE, DEVICE_TOKEN_REVOKED |
The register’s session is invalid: reconnect it with the same name |
| 409 | DEVICE_NAME_TAKEN |
The name is already held by another active register (when connecting) |
API v1. The register key
xdev_…and the/v1/...addresses are still supported. There the register is determined by the key itself, sodevice_nameis not needed in the body, but reconnecting a register needs a new key. Use v2 for new integrations.