Connecting a Cash Register and Getting an API v2 Key

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.

What a cash register is

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.

Why you need it

Requirements

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 («Тариф и баланс»)

How it works

Cashier's number -> SMS code from Kaspi -> register in xpayment -> API v2 key (xapi_…) -> your requests
  1. You enter the cashier’s number in the wizard.
  2. Kaspi sends an SMS code to that number.
  3. You enter the code, and xpayment establishes a protected session with your Kaspi Pay account. For that, xpayment creates its own cryptographic key pair (ECDSA P-256) for the register.
  4. The register appears in the dashboard. Next you create an 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.

Connecting a cash register: step by step

A three-step wizard connects the register. Open Кассы и счета (Cash registers and accounts) and select Подключить кассу (Connect a cash register).


Step 1. Check that everything is ready

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).


Step 2. The cashier’s number

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:

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:


Step 3. The SMS code

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.


Step 4. Create an API v2 key

  1. Open API-ключи (API keys) → Ключи API v2 (API v2 keys).
  2. Create a key and give it a name (for example, “Website”).
  3. Copy the value that looks like 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:

  1. Keep it in the backend’s environment variables (.env) or in a secret manager.
  2. Do not commit it to a repository and do not put it in the frontend.
  3. Use separate keys for different systems (website, CRM, bot): it is easier to revoke them one by one. The maximum is 10 active keys per user.

Check the connection

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.

If the register needs to be reconnected

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.

Using the key in your application

The register is connected and you have the xapi_… key. Now connect it to your backend.

Quick start: the first request

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.

Integration examples

Keep the key in an environment variable and never send it to the browser.

Node.js

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, ... }
}

Python

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

<?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);
}

Key points

  1. The key lives only on the server. If it ended up in a browser, a repository, or a log, revoke it in API-ключи (API keys) and create a new one.
  2. The register name goes in config. Keep device_name in settings, not in code: it makes switching between the live and the test register easy.
  3. Idempotency. For POST /v2/payments, send X-Idempotency-Key so a repeated request does not create a duplicate.
  4. Confirm with a webhook. Do not mark an order paid when a link is created: wait for payment.completed.
  5. Test in the sandbox with an xapi_test_… key and the register test: Sandbox.

Possible errors

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, so device_name is not needed in the body, but reconnecting a register needs a new key. Use v2 for new integrations.

What next