How the xpayment Virtual Cashier and the API v2 Key Work

How a Kaspi Pay cashier becomes a cash register in xpayment, why an API v2 key beats a per-register key, and what you get for a website, bot, CRM, or n8n.

If a business already has Kaspi Pay and a separate cashier, the next step is to turn that cashier into a safe API channel for your product. In xpayment.kz this looks like a chain of a Kaspi Pay cashier, a cash register in your dashboard, and an xapi_… key with which your backend manages payments.

A note on terms. In the dashboard this entity is called a cash register («Кассы и счета»), in API v2 you choose it by device_name, and in API v1 and internal names it is called a device. When we explain the integration to businesses we say virtual cashier: for the user it is already a connected cashier on the xpayment side. All four words mean the same thing.

xpayment is not an official Kaspi product. It is an independent integration platform: it supports Kaspi Pay today and is built as one layer for online payments, with other payment systems to come. This article explains the architecture and the point of the connection. For the step-by-step process with screens, see Connecting a cash register and getting an API v2 key.

The short answer

The logic is:

Kaspi Pay cashier -> register in xpayment (virtual cashier, device_name) -> API v2 key xapi_… -> your application -> webhook with the payment status

After connecting, your product can:

What a virtual cashier is

A virtual cashier in xpayment is not a new employee in Kaspi Pay. It is a connection model in which an already created Kaspi Pay cashier becomes a safe API channel for your product.

connecting a cash register in xpayment = adding a new virtual cashier

Entity Where it lives What it is for
Cashier Kaspi Pay A restricted role for accepting payments
Cash register / virtual cashier xpayment («Кассы и счета») Ties the cashier’s number to your dashboard; the API name (device_name)
API v2 key xapi_… xpayment («API-ключи») Your backend’s access to payments of all your registers
Webhook Your server Automatic status updates

On the Kaspi Pay side you still work with the ordinary Cashier role. On the xpayment side that cashier appears as a cash register that can be safely connected to your product.

Why the API v2 key is more convenient

In API v1 an xdev_… key is tied to one register: when you reconnect the register you need a new key, and the code has to change. API v2 works differently:

API v1 is still supported, but we recommend v2 for new integrations.

Why the scheme looks reliable

xpayment does not ask for access to the business owner’s main account. We build the connection around the restricted cashier role that Kaspi Pay describes in its official materials:

A cashier cannot transfer money or see others’ operations, and buyers’ money goes directly to your Kaspi account. You need neither a bank contract nor a VPN: you use your existing Kaspi Pay account.

What to prepare before connecting

  1. A Kaspi Pay cashier with a separate phone number (not the owner of another Kaspi Pay account).
  2. The cashier’s phone at hand: the SMS code will arrive on it.
  3. Access to the xpayment.kz dashboard.
  4. A payment flow in mind: a payment link, QR, deeplink, or a phone invoice.
  5. A public HTTPS address for the webhook, if statuses must reach a CRM, website, SaaS, or n8n.

If the cashier does not exist yet, first go through How to add a Kaspi Pay cashier for online payments.

What the connection looks like in xpayment

  1. Sign in to xpayment.
  2. Open Кассы и счета (Cash registers and accounts) → Подключить кассу (Connect a cash register).
  3. Tick the three checks, then enter the register name, the “Имя для API” (API name), and the cashier’s number.
  4. Enter the code from the SMS.
  5. In API-ключи (API keys), create an API v2 key xapi_….

The full process with screens: Connecting a cash register and getting an API v2 key.

What you get once the key is issued

The xapi_… key does not give “access to all of Kaspi”. It opens specific payment capabilities through xpayment:

Capability Where to go next
Send a customer an invoice by phone number Remote payments via POST /v2/payments
Create a payment link, QR, or deeplink Payment links via POST /v2/payments/link
Get payment confirmation automatically xpayment webhooks
Make a refund or cancel a payment Payment statuses and refunds
Test without real money Sandbox
Manage plans and access of SaaS users Subscriptions API

The point of a virtual cashier is not to manually “press one more button” but to get a managed API flow for a website, CRM, bot, SaaS, or no-code scenario.

Where this model is especially useful

Product What a virtual cashier gives
An online store The checkout creates a payment automatically and waits for a webhook
A Telegram bot The bot sends a link, QR, or invoice with no manual cashier work
A CRM A manager invoices a customer by phone number
SaaS / billing A payment is created from an invoice or subscription flow
n8n The HTTP Request node calls the API, the Webhook node updates the CRM or ERP

Rules to follow from the start

  1. Connect only a cashier, not the owner’s main account.
  2. Keep the xapi_… key only on the server or in a secret manager.
  3. Save merchant_order_id as your internal order identifier.
  4. Use X-Idempotency-Key where requests may be repeated.
  5. Change the order status on a webhook, not when a link is opened or a request is created.
  6. Verify the signature of every webhook.

What to read next