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

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

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

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

xpayment не является официальным продуктом Kaspi. Это независимая интеграционная платформа, которая сейчас поддерживает Kaspi Pay и строится как единый API-слой для онлайн-платежей. Эта статья объясняет именно архитектуру и смысл такого подключения. Если нужен пошаговый UI-процесс, откройте Подключение устройства и получение API-ключа.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если кассир еще не создан, сначала пройдите Как добавить кассира в Kaspi Pay для онлайн-платежей.

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

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

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

Эта статья намеренно оставляет маршрут кратким, чтобы не повторять экран-за-экраном инструкцию. Полный UI-процесс добавления устройства, то есть виртуального кассира, вынесен отдельно: Подключение устройства и получение API-ключа.

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

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

Возможность Куда идти дальше
Отправить клиенту удаленный счет по номеру телефона Приём удалённых платежей через POST /payments
Создать payment link, QR или deeplink Платёжные ссылки через POST /payments/link
Получить подтверждение оплаты автоматически Вебхуки: как xpayment уведомляет ваш сервер о платежах
Проверить статус вручную как fallback Документация xpayment API

Поэтому основной смысл виртуального кассира не в том, чтобы вручную «нажать еще одну кнопку», а в том, чтобы получить управляемый 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, а не по факту открытия ссылки или запроса.

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