Полное руководство по подключению: от Kaspi до первого платежа

Пошаговый гид: создайте кассира в Kaspi Pay, настройте webhooks, добавьте устройство и получите API-ключ xpayment.

Добро пожаловать в xpayment

Это обзорный маршрут подключения xpayment к Kaspi Pay. Он нужен, чтобы быстро понять последовательность шагов и не потеряться в процессе. Подробные инструкции по каждому этапу вынесены в отдельные статьи и официальные материалы Kaspi / Kaspi Pay.

Если вам нужен не общий маршрут, а конкретная задача, переходите сразу в нужный материал.

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

1. Подготовить Kaspi Pay и добавить кассира
   • Практический гид: Как добавить кассира в Kaspi Pay для онлайн-платежей
   • Официальные материалы: Kaspi Pay для бизнеса, Как добавить кассира, Как кассиру начать принимать оплату
2. Войти в xpayment и настроить webhook
   • Технический разбор: Вебхуки: как xpayment уведомляет ваш сервер о платежах
3. Подключить устройство и получить API-ключ
   • Концепция: Как создать виртуального кассира xpayment и получить API
   • Полный экран-за-экраном процесс: Подключение устройства и получение API-ключа
4. Выбрать платежный сценарий
   • Сначала сравнение: QR, deeplink или удаленная оплата по телефону
   • Потом реализация: Приём удалённых платежей через POST /payments или Платёжные ссылки через POST /payments/link

Что вам понадобится

Перед началом проверьте, что у вас есть:

Что нужно	Зачем
Смартфон с приложением Kaspi Pay	Для бизнеса и кассира
Отдельный номер телефона	Для ограниченной роли кассира
Аккаунт Google	Для входа в xpayment
Webhook URL	Чтобы ваша система получала статусы платежей

Что вы получите в итоге

После прохождения этих этапов у вас будет:

1. Ограниченный кассир в Kaspi Pay вместо доступа к основному аккаунту владельца
2. Устройство в xpayment и API-ключ xdev_...
3. Webhook-уведомления для изменения статусов заказов
4. Подходящий сценарий приема оплаты для сайта, бота, CRM, SaaS или n8n

Дальше в этом обзоре каждая часть кратко объясняет, что именно нужно сделать и куда перейти за полной инструкцией.

Часть 1 — Подготовка Kaspi Pay

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

Полный разбор этого этапа: Как добавить кассира в Kaspi Pay для онлайн-платежей

Что нужно проверить в Kaspi Pay

Перед переходом в xpayment убедитесь, что:

1. У вас есть активный бизнес-аккаунт Kaspi Pay.
2. В Kaspi Pay создана или доступна точка продаж.
3. У вас есть отдельный номер телефона для кассира.
4. Кассир может войти в приложение Kaspi Pay по SMS-ссылке.

Почему мы используем именно кассира

xpayment не должен работать с основным аккаунтом владельца бизнеса. Безопасная модель строится вокруг роли Кассир, потому что она ограничена и предназначена только для приема оплат.

Официальные материалы Kaspi, на которые стоит опираться на этом этапе:

• Kaspi Pay для бизнеса
• Как добавить кассира
• Как кассиру начать принимать оплату
• Как добавить точку продаж

Что сделать сейчас

1. Если Kaspi Pay еще не подключен, активируйте бизнес-аккаунт в приложении Kaspi Pay.
2. Добавьте кассира по пути Сервисы -> Профиль компании -> Сотрудники.
3. Привяжите кассира к нужной точке продаж.
4. Сохраните номер кассира: он понадобится при подключении устройства в xpayment.

Если вам нужен именно этот этап в деталях, не продолжайте отсюда вслепую — откройте отдельную статью про кассира и пройдите ее полностью. После этого возвращайтесь к Части 2.

Часть 2 — Вход в xpayment и настройка вебхука

Теперь, когда кассир готов в Kaspi Pay, переходите в xpayment. На этом этапе две задачи: войти в панель управления и создать webhook, через который ваша система будет получать статусы платежей.

Что сделать в xpayment

Шаг 2.1 — Войдите в xpayment

1. Откройте xpayment.kz в браузере.
2. Нажмите Войти через Google.
3. Выберите нужный аккаунт Google.

Шаг 2.2 — Создайте webhook

1. Перейдите в раздел Вебхуки.
2. Нажмите + Новый вебхук.
3. Укажите URL вашего backend-эндпоинта или выберите готовую интеграцию, если используете платформу-партнера.
4. Включите платежные события, которые должны менять статус заказа в вашей системе.
5. Сохраните webhook.

Для большинства проектов достаточно сразу включить payment.completed, payment.cancelled и payment.failed. Если вы используете возвраты, добавьте события refund.

Куда идти за полной инструкцией

Эта статья оставляет здесь только маршрут. Полное объяснение, зачем нужен webhook, как он работает, как защищать endpoint и какие события обрабатывать, вынесено в отдельный материал:

• Вебхуки: как xpayment уведомляет ваш сервер о платежах

После настройки webhook переходите к Части 3 — подключению устройства и выпуску API-ключа.

Часть 3 — Добавление устройства и получение API-ключа

На этом этапе вы связываете телефон кассира с xpayment как устройство и получаете API-ключ xdev_.... Это тот ключ, которым ваш backend будет создавать платежи.

Что сделать

1. Откройте раздел Устройства.
2. Добавьте новое устройство с номером кассира из Части 1.
3. Получите OTP на телефон кассира и подтвердите привязку.
4. Создайте API-ключ и сохраните его в безопасном месте.

Важно не пропустить

• Используйте номер кассира, а не основной номер владельца бизнеса.
• Телефон кассира должен быть рядом в момент OTP-подтверждения.
• API-ключ показывается один раз, поэтому его нужно сохранить сразу.
• Ключ хранится только на сервере или в менеджере секретов, не в frontend.

Где читать полный разбор

Чтобы не дублировать пошаговый мастер подключения, используйте два более точных материала:

• Как создать виртуального кассира xpayment и получить API — объясняет, что именно вы создаёте и зачем это нужно
• Подключение устройства и получение API-ключа — показывает полный UI-процесс, OTP и выпуск ключа экран за экраном

После того как устройство добавлено и ключ сохранен, переходите к Части 4 — выбору способа интеграции и платежного сценария.

Часть 4 — Подключение к вашей платформе

Итак, у вас есть API-ключ. Дальнейшие действия зависят от того, как именно вы хотите принимать оплату: через платежную ссылку, через удаленный счет по номеру телефона или через готовую платформу-партнера.

---

Вариант А — платформы-партнёры (например, tec.delivery)

Если вы работаете на одной из платформ-партнёров xpayment (например, tec.delivery) — всё просто:

1. Войдите в свой аккаунт на tec.delivery
2. Перейдите в Настройки компании
3. Найдите раздел, связанный с оплатой или xPayment
4. Вставьте ваш API-ключ (xdev_...) в соответствующее поле
5. Сохраните настройки

После этого онлайн-платежи через Kaspi Pay будут работать в вашем заведении автоматически.

Список платформ-партнёров xpayment будет расширяться — следите за обновлениями.

---

Вариант Б — REST API и другие сервисы

Если вы разработчик или ваш сервис поддерживает прямое подключение по API — можно работать с xpayment напрямую.

Рекомендуемый порядок такой:

1. Сначала откройте обзор выбора сценария: QR, deeplink или удаленная оплата по телефону
2. Затем переходите в подробную реализацию нужного потока:
   • Приём удалённых платежей через POST /payments
   • Платёжные ссылки через POST /payments/link
3. Для подтверждения статусов всегда настройте вебхуки

Откройте страницу Документации API — она интерактивная: вы можете вставить свой ключ и сразу протестировать любой запрос прямо в браузере, без дополнительных инструментов.

Как начать работу с /docs:

1. Откройте xpayment.kz/docs
2. В поле Bearer Token в верхней части страницы вставьте ваш ключ (xdev_...)
3. Нажмите Авторизовать — теперь все запросы на странице будут автоматически использовать ваш ключ
4. Выберите любой эндпоинт (например, POST /payments), нажмите Попробовать, заполните параметры и отправьте запрос

Полная документация всех эндпоинтов, форматов запросов и ответов доступна там же.

---

Готово!

Вы прошли весь путь от нуля до работающей интеграции:

• ✅ Открыли бизнес-аккаунт Kaspi Pay
• ✅ Создали кассира со строго ограниченными правами
• ✅ Настроили вебхуки — ваша система будет получать уведомления о каждом платеже
• ✅ Добавили устройство и получили API-ключ
• ✅ Подключили xpayment к вашей платформе

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

Если что-то пошло не так или возник вопрос — ознакомьтесь с другими статьями в нашем разделе руководств или обратитесь в поддержку.