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

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

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

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

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

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

1. **Подготовить Kaspi Pay и добавить кассира**
	- Практический гид: [Как добавить кассира в Kaspi Pay для онлайн-платежей](https://xpayment.kz/blog/kaspi-pay-cashier-setup)
	- Официальные материалы: [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)
2. **Войти в xpayment и настроить webhook**
	- Технический разбор: [Вебхуки: как xpayment уведомляет ваш сервер о платежах](https://xpayment.kz/blog/webhooks)
3. **Подключить устройство и получить API-ключ**
	- Концепция: [Как создать виртуального кассира xpayment и получить API](https://xpayment.kz/blog/xpayment-virtual-cashier-api)
	- Полный экран-за-экраном процесс: [Подключение устройства и получение API-ключа](https://xpayment.kz/blog/device-setup)
4. **Выбрать платежный сценарий**
	- Сначала сравнение: [QR, deeplink или удаленная оплата по телефону](https://xpayment.kz/blog/kaspi-pay-payment-options)
	- Потом реализация: [Приём удалённых платежей через POST /payments](https://xpayment.kz/blog/direct-payment) или [Платёжные ссылки через POST /payments/link](https://xpayment.kz/blog/payment-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 для онлайн-платежей](https://xpayment.kz/blog/kaspi-pay-cashier-setup)

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

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

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

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

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

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

- [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)
- [Как добавить точку продаж](https://guide.kaspi.kz/partner/ru/profile/sales_point/q1710)

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

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

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

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

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

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

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

1. Откройте [xpayment.kz](https://xpayment.kz) в браузере.
2. Нажмите **Войти через Google**.
3. Выберите нужный аккаунт Google.

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

1. Перейдите в раздел **[Вебхуки](https://xpayment.kz/app/webhooks)**.
2. Нажмите **+ Новый вебхук**.
3. Укажите URL вашего backend-эндпоинта или выберите готовую интеграцию, если используете платформу-партнера.
4. Включите платежные события, которые должны менять статус заказа в вашей системе.
5. Сохраните webhook.

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

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

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

- [Вебхуки: как xpayment уведомляет ваш сервер о платежах](https://xpayment.kz/blog/webhooks)

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

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

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

## Что сделать

1. Откройте раздел **[Устройства](https://xpayment.kz/app/devices)**.
2. Добавьте новое устройство с номером кассира из Части 1.
3. Получите OTP на телефон кассира и подтвердите привязку.
4. Создайте API-ключ и сохраните его в безопасном месте.

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

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

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

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

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

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

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

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

---

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

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

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

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

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

---

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

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

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

1. Сначала откройте обзор выбора сценария: [QR, deeplink или удаленная оплата по телефону](https://xpayment.kz/blog/kaspi-pay-payment-options)
2. Затем переходите в подробную реализацию нужного потока:
	- [Приём удалённых платежей через POST /payments](https://xpayment.kz/blog/direct-payment)
	- [Платёжные ссылки через POST /payments/link](https://xpayment.kz/blog/payment-link)
3. Для подтверждения статусов всегда настройте [вебхуки](https://xpayment.kz/blog/webhooks)

Откройте страницу **[Документации API](https://xpayment.kz/docs)** — она интерактивная: вы можете вставить свой ключ и сразу протестировать любой запрос прямо в браузере, без дополнительных инструментов.

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

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

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

---

## Готово!

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

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

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

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

## Читайте также
- [Подключение устройства](https://xpayment.kz/blog/device-setup)
- [Webhooks xpayment](https://xpayment.kz/blog/webhooks)

---

Источник: https://xpayment.kz/blog/onboarding