# Как создать виртуального кассира xpayment и получить API

Как подключить кассира Kaspi Pay к xpayment, получить API-ключ устройства и принимать онлайн-платежи в сайте, боте, CRM или n8n.

Если у бизнеса уже есть Kaspi Pay и отдельный кассир, следующий шаг - превратить этого кассира в безопасный API-канал для вашего продукта. Внутри [xpayment.kz](https://xpayment.kz/) это выглядит как связка из кассира Kaspi Pay, **устройства** и ключа `xdev_...`, которым ваш backend управляет платежами.

Важная оговорка по терминологии: внутри проекта и интерфейса xpayment эта сущность называется **устройством**. Когда мы объясняем интеграцию бизнесу, то называем то же самое **виртуальным кассиром**, потому что для пользователя это уже подключённый кассир на стороне xpayment.

xpayment не является официальным продуктом Kaspi. Это независимая интеграционная платформа, которая сейчас поддерживает Kaspi Pay и строится как единый API-слой для онлайн-платежей. Эта статья объясняет именно архитектуру и смысл такого подключения. Если нужен пошаговый UI-процесс, откройте [Подключение устройства и получение API-ключа](https://xpayment.kz/blog/device-setup).

## Короткий ответ

Логика подключения такая:

```text
Кассир Kaspi Pay -> устройство в xpayment (виртуальный кассир) -> API-ключ xdev_... -> ваше приложение -> webhook о статусе платежа
```

После подключения ваш продукт получает понятные возможности:

- отправлять клиенту удаленный счет по номеру телефона;
- создавать payment link, QR или deeplink;
- получать webhook после оплаты;
- проверять статус платежа по `payment_id`;
- связывать платежи со своими заказами через `merchant_order_id`.

## Что такое виртуальный кассир

Виртуальный кассир в xpayment - это не новый сотрудник в Kaspi Pay. Это модель подключения, в которой уже созданный кассир Kaspi Pay превращается в безопасный API-канал для вашего продукта.

При этом внутри самого проекта и API эта сущность называется **устройством**. То есть формула простая:

> **добавить новое устройство в xpayment = добавить нового виртуального кассира**

Мы используем выражение «виртуальный кассир», когда объясняем бизнесу смысл интеграции. В интерфейсе xpayment, документации по устройствам и в ключе `xdev_...` речь идёт про ту же самую сущность.

| Сущность | Где находится | Зачем нужна |
|---|---|---|
| Кассир | Kaspi Pay | Ограниченная роль для приема платежей |
| Устройство / виртуальный кассир | xpayment | Привязка номера кассира к вашему кабинету и выпуск API-ключа |
| API-ключ | xpayment | Доступ вашего backend к платежам |
| Webhook | Ваш сервер | Автоматическое обновление статусов |

На стороне Kaspi Pay вы по-прежнему работаете с обычной ролью **Кассир**. На стороне xpayment этот кассир появляется как **устройство**, которое можно безопасно подключить к вашему продукту.

## Почему эта схема выглядит надежно

xpayment не просит доступ к основному аккаунту владельца бизнеса. Логика строится вокруг ограниченной роли кассира, которую Kaspi Pay описывает в своих официальных материалах.

Опираться стоит на эти источники:

- [Kaspi Pay для бизнеса](https://kaspi.kz/kaspipay)
- [Как добавить кассира](https://guide.kaspi.kz/partner/ru/profile/user/cashier/q1402)
- [Как кассиру начать принимать оплату](https://guide.kaspi.kz/partner/ru/profile/user/cashier/q1414)

Именно поэтому xpayment корректно описывать как независимую интеграционную платформу поверх реального процесса Kaspi Pay, а не как «официальный API Kaspi».

## Что подготовить перед подключением

Перед подключением устройства проверьте базовый минимум:

1. У вас есть **кассир Kaspi Pay** с отдельным номером телефона.
2. Телефон кассира находится рядом для **OTP-подтверждения**.
3. У вас есть доступ в кабинет [xpayment.kz](https://xpayment.kz/).
4. Понятно, какой сценарий оплаты вам нужен: payment link, QR, deeplink или удаленный счет по номеру телефона.
5. Готов **webhook URL**, если статусы должны попадать в CRM, сайт, SaaS или n8n.

Если кассир еще не создан, сначала пройдите [Как добавить кассира в Kaspi Pay для онлайн-платежей](https://xpayment.kz/blog/kaspi-pay-cashier-setup).

## Как выглядит подключение в xpayment

Сам маршрут короткий:

1. Войти в xpayment.
2. Открыть раздел устройств.
3. Добавить номер кассира как новое устройство, то есть как нового виртуального кассира.
4. Подтвердить привязку по OTP.
5. Выпустить ключ `xdev_...`.

Эта статья намеренно оставляет маршрут кратким, чтобы не повторять экран-за-экраном инструкцию. Полный UI-процесс добавления устройства, то есть виртуального кассира, вынесен отдельно: [Подключение устройства и получение API-ключа](https://xpayment.kz/blog/device-setup).

## Что вы получаете после выпуска API-ключа

Ключ `xdev_...` не дает «доступ ко всему Kaspi». Он открывает конкретные платежные возможности через xpayment:

| Возможность | Куда идти дальше |
|---|---|
| Отправить клиенту удаленный счет по номеру телефона | [Приём удалённых платежей через POST /payments](https://xpayment.kz/blog/direct-payment) |
| Создать payment link, QR или deeplink | [Платёжные ссылки через POST /payments/link](https://xpayment.kz/blog/payment-link) |
| Получить подтверждение оплаты автоматически | [Вебхуки: как xpayment уведомляет ваш сервер о платежах](https://xpayment.kz/blog/webhooks) |
| Проверить статус вручную как fallback | [Документация xpayment API](https://xpayment.kz/docs) |

Поэтому основной смысл виртуального кассира не в том, чтобы вручную «нажать еще одну кнопку», а в том, чтобы получить управляемый API-поток для сайта, CRM, бота, SaaS или no-code сценария.

## Где такая модель особенно полезна

| Продукт | Что дает виртуальный кассир |
|---|---|
| Интернет-магазин | Checkout автоматически создает платеж и ждет webhook |
| Telegram-бот | Бот отправляет ссылку, QR или удаленный счет без ручной работы кассира |
| CRM | Менеджер выставляет счет клиенту по номеру телефона |
| SaaS / биллинг | Платеж создается из invoice- или subscription-потока |
| n8n workflow | HTTP Request вызывает API, Webhook node обновляет CRM или ERP |

## Правила, которые лучше соблюдать сразу

1. Подключайте только **кассира**, а не основной аккаунт владельца.
2. Храните `xdev_...` только на сервере или в менеджере секретов.
3. Сохраняйте `merchant_order_id` как ваш внутренний идентификатор заказа.
4. Используйте `X-Idempotency-Key` там, где возможны повторные запросы.
5. Финальный статус заказа меняйте по webhook, а не по факту открытия ссылки или запроса.

## Что читать дальше

- Для настройки кассира: [Как добавить кассира в Kaspi Pay для онлайн-платежей](https://xpayment.kz/blog/kaspi-pay-cashier-setup)
- Для полного UI-подключения: [Подключение устройства и получение API-ключа](https://xpayment.kz/blog/device-setup)
- Для выбора платежного сценария: [QR, deeplink или удаленная оплата по телефону](https://xpayment.kz/blog/kaspi-pay-payment-options)
- Для реализации API: [Платёжные ссылки через POST /payments/link](https://xpayment.kz/blog/payment-link) и [Приём удалённых платежей через POST /payments](https://xpayment.kz/blog/direct-payment)

## Читайте также
- [Как добавить кассира в Kaspi Pay](https://xpayment.kz/blog/kaspi-pay-cashier-setup)
- [QR, deeplink и удаленная оплата](https://xpayment.kz/blog/kaspi-pay-payment-options)
- [Webhooks xpayment](https://xpayment.kz/blog/webhooks)

---

Источник: https://xpayment.kz/blog/xpayment-virtual-cashier-api