> Источник: https://apipay.kz/guides/podklyuchenie-apipay-mcp · Обновлено: 2026-10-26 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

# Как сделать свой сервис на оплатах Kaspi с ИИ: ApiPay и MCP

Да, свой сервис на оплатах Kaspi — магазин, бот, сводку продаж — можно собрать с ИИ-помощником (Claude Code, Codex, Cursor и другие) через ApiPay: дайте агенту страницу [apipay.kz/for-ai](/for-ai), и он напишет код, а счета, статусы оплаты и возвраты ваш сервис получает через [API ApiPay](/kaspi-api). Начать можно в песочнице сразу после регистрации, без кассира и настоящих денег; если ваш ИИ-клиент поддерживает MCP, настройку подключения для него берите на экране [«Подключить с ИИ»](/setup/ai): через MCP помощник ведёт подключение по шагам по одной фразе «Встрой apipay», а после вашего входа видит ход подключения и проверяет оплату, отмену, возврат и уведомления в песочнице. Помощник, который работает прямо в проекте с терминалом (Claude Code, Codex), без MCP подключение не начинает: он скажет, что MCP не подключён, и попросит подключить его на этом экране.

## Что можно собрать на оплатах Kaspi с ИИ?

ApiPay — независимый сервис поверх вашего Kaspi Pay: ваше приложение обращается к API ApiPay с ключом `X-API-Key`, а покупатель платит в Kaspi как обычно. Всё, что ниже, помощник пишет по [apipay.kz/for-ai](/for-ai), а точные поля сверяет с [документацией API](/docs).

| Задача | Что использует ваш сервис |
|---|---|
| Выставить счёт покупателю | `POST /invoices` — счёт по номеру телефона |
| Узнать, оплачен ли счёт | уведомления (webhook) — обязательны, если подключаете через MCP; опрос `GET /invoices/{id}` с сервера — для быстрого старта и как сверка |
| Вернуть деньги | `POST /invoices/{id}/refund` |
| Сводка и аналитика продаж | `GET /invoices` и `GET /invoices/stats` |

Для аналитики: в списке счетов видны и продажи, проведённые в приложении Kaspi Pay мимо ApiPay, — фильтр `origin=kaspi`. Такие продажи подтягиваются из истории Kaspi не сразу и не всегда полностью и датируются временем самой операции: для отчётов перезапрашивайте прошедший период целиком, а итоги по кассовой смене берите из `GET /cashbox/reconciliation`. `GET /invoices/stats` считает суммы и конверсию за период. Общий лимит — до 200 запросов в минуту на ключ.

## Нужно ли уметь программировать?

Код пишет помощник, но сервису нужна серверная часть: ключ ApiPay живёт только на сервере и не попадает в код страницы в браузере. Если серверной части нет, помощник добавит серверную функцию. Если свой сервис не нужен, счета выставляются прямо из кабинета — см. [ApiPay без программиста](/guides/apipay-bez-programmista).

## С чего начать?

1. Зарегистрируйтесь в ApiPay. Песочница открывается сразу, анкета и кассир для неё не нужны. Если ваша организация уже принимает платежи, не переключайте её обратно в тестовый режим ради проверки: пока он включён, настоящие счета покупателям не уходят.
2. Нажмите **«Скопировать инструкцию»** на экране [«Подключить с ИИ»](/setup/ai) (или **«Скопировать инструкцию без ключей»** при создании ключа) и передайте текст помощнику. Инструкция короткая — «Встрой apipay» и ссылка на [apipay.kz/SKILL.md](/SKILL.md) для помощника без MCP.
3. Ключ и секрет в файл `.env` проекта кладёт программа ApiPay, которую запускает помощник: он пришлёт ссылку и код, а вы подтвердите выпуск в кабинете (см. «Как ключ попадает в проект» ниже). Код не совпал или устарел — помощник пришлёт новые ссылку и код. Файл исключите из Git.
4. Помощник изучит проект и уточнит только бизнес-вопросы: за что платит клиент, откуда берётся сумма и что должно произойти после оплаты.
5. Он пишет код и проверяет его в песочнице: создаёт тестовый счёт, симулирует оплату через `POST /invoices/{id}/simulate-status` и проверяет, что заказ в вашем приложении изменился. Успех, отмену и истечение проверяйте на разных тестовых заказах.
6. Для настоящих платежей заполните анкету о бизнесе, дождитесь одобрения и подключите кассира в [мастере по SMS](/connect-cashier). Приём платежей идёт по тарифу; первые 3 дня после подключения кассира бесплатны, если организации доступен пробный тариф. Рабочий режим вы включаете сами: помощник пришлёт ссылку и код, вы сверите код и подтвердите перевод кнопками на экране; перед сменой режима кабинет попросит подтвердить удаление тестовых данных.

Подробный маршрут с временем на каждый шаг — в [настройке ApiPay за 15 минут](/guides/nastroyka-apipay-za-15-minut), технические детали для помощника — в [интеграции с помощью ИИ](/guides/integratsiya-apipay-s-pomoshchyu-ii).

## Как подключить ApiPay к Claude Code, Codex или Cursor через MCP?

Откройте экран [«Подключить с ИИ»](/setup/ai): в кабинете он открывается кнопкой «Подключить с ИИ» в разделе Настройки → «Подключение». Выберите свой ИИ-клиент и скопируйте настройку: для Claude Code и Codex это команды для терминала, для Cursor — JSON для настроек MCP. Адрес сервиса — `https://mcp.apipay.kz/mcp`, имя сервера в настройке — `apipay-setup`. API-ключ не используется для входа в MCP, в настройки ИИ-клиента его не добавляйте.

Дальше достаточно написать помощнику «Встрой apipay». Через MCP он ведёт подключение по шагам: задаёт вам только недостающие вопросы, берёт готовый код под ваш стек и справочник ApiPay. Это работает и без входа. Ключей и других секретов в ответах MCP нет.

MCP — помощник для настройки, а не замена API: счета и возвраты создаёт ваше приложение. Помощник с терминалом без MCP подключение не начнёт: он попросит сначала подключить MCP и снова написать ему «Встрой apipay». Помощник без терминала (чат в браузере, конструктор сайтов) работает по инструкции и [apipay.kz/for-ai](/for-ai). Устанавливайте только то, что показано на этом экране.

## Как войти в MCP и что помощник сможет после входа?

Для входа выполните вторую команду из настройки или согласитесь, когда ИИ-клиент сам предложит войти: в браузере откроется страница ApiPay. Войдите в свой кабинет, проверьте название приложения, отметьте организации, с которыми помощник будет работать, и нажмите **«Разрешить»**. Если вы сами только что не начинали подключение, нажмите «Отклонить».

Помощник работает с тестовой организацией. Организацию, которая принимает настоящие платежи, вы открываете ему отдельно в кабинете: Настройки → «Кто имеет доступ к организации» → «ИИ-агенты». В Cursor вход не поддерживается — там работают только шаги без входа: вопросы, код и справочник.

После входа помощник видит ход подключения и следующий шаг, выбирает для интеграции уже выпущенный ключ, ставит адрес уведомлений тестовой версии сайта и проверяет в песочнице оплату, отмену, истечение, ошибку, возврат, отказ в возврате, возврат по ссылке после отказа и повторное уведомление. Анкета о бизнесе для этого не нужна. Он читает журнал запросов и журнал доставок уведомлений, а когда проверки пройдены, спрашивает «Мы готовы. Выходим в прод?» и готовит черновик анкеты. Изменился ли заказ в вашем магазине, помощник проверяет сам — по журналу вашего приложения и записи заказа. На странице «Подключение с ИИ» у таких проверок подпись «сообщил ваш ИИ-помощник» — это не проверка ApiPay: перед ответом «да» на «Выходим в прод?» откройте пару тестовых заказов и посмотрите сами.

Свой доступ можно отозвать в любой момент: Настройки → «Кто имеет доступ к организации» → «ИИ-агенты»; помощник потеряет доступ ко всем вашим организациям. Там же владелец видит, кто из разработчиков разрешил доступ ИИ-агенту; такой доступ снимается, только если убрать разработчика из организации.

## Что вы делаете сами, а что помощник?

В браузере — только вы: вход и разрешение доступа, выпуск ключа и секрета уведомлений, отправка анкеты о бизнесе (рассказ о бизнесе, ссылка на витрину и 1–3 скриншота; черновик может подготовить помощник, а название организации, БИН или ИИН, скриншоты и галочку вводите вы), код из SMS для кассира, оплата тарифа и включение рабочего режима. Помощник даёт ссылку на нужный экран кабинета, а сами эти действия через MCP не выполняются. Если помощник пишет, что сделал их сам, проверьте в кабинете. Помощник пишет код, запускает тесты в песочнице и показывает, что проверено, а что нет. Само приложение на время проверок запускаете вы: помощник второй экземпляр не поднимает и попросит вас перезапустить приложение, если оно не отвечает или не подхватило изменения. Код на рабочий сервер выкладываете вы или ваш разработчик: помощник не выкладывает его и не настраивает выкладку, даже если попросить.

Если тест упал, инструкция просит помощника отделить доказанное от предположения, предложить конкретное исправление и дождаться вашего согласия, а после правки — повторить тест. Ответ HTTP 200 подтверждает доставку, но не то, что заказ изменился правильно, — это проверяется в самом приложении.

После анкеты, кассира или оплаты тарифа кабинет покажет готовую фразу для помощника. Скопируйте её и отправьте в **тот же чат**; код из SMS и данные анкеты в чат не пересказывайте. После выпуска ключа и перевода в рабочий режим по ссылке помощника писать ему ничего не нужно: он продолжит сам. Если вы разрешили помощнику доступ, он может сам перечитать ход подключения. Если нет — результат он не видит, и итог смотрите на этой странице сами.

## Как ключ попадает в проект без копирования?

Копировать ничего не нужно. Помощник запускает на вашем компьютере программу ApiPay (`apipay-cli`, ей нужен Node.js 18+) и присылает в чат ссылку и код из восьми букв, например `KXRT-BZMQ`.

1. Откройте ссылку и войдите в кабинет.
2. Сверьте код на экране с кодом, который написал помощник. Не совпадает или вы ничего не запускали — нажмите **«Это не я»**.
3. Отметьте галочку, что команду на компьютере запустили вы сами или по вашей просьбе ИИ-помощник или разработчик. Если организация уже принимает настоящие платежи, отметьте и вторую галочку — что счета будут настоящими. Затем нажмите **«Выпустить ключ для проекта»**.
4. На экране появится «Ключ выпущен». Помощник сам заберёт ключ и продолжит — писать ему ничего не нужно. Если он молчит дольше пары минут, отправьте ему в тот же чат фразу с экрана.

Программа сама запишет ключ и секрет уведомлений в файл `.env` проекта. На экране кабинета и в чате значений нет — так и задумано. Секрет к уже выпущенному ключу без секрета выпускается так же, кнопкой **«Выпустить секрет для проекта»**.

**Ссылку и код присылает только ваш помощник в вашем чате.** Если такие ссылку и код вам прислали в мессенджере, по почте или по телефону — нажмите «Это не я»: иначе ключ к вашей организации получит тот, кто их прислал.

Программа пишет ключ только в файл на этом компьютере. На рабочий сервер или хостинг значения переносите сами. Код действует ограниченное время — срок помощник присылает вместе с кодом. Если код не совпал или страница пишет, что он больше не действует, напишите помощнику — он пришлёт новые ссылку и код. Если на компьютере нет Node.js, помощник попросит установить его (версию LTS с [nodejs.org](https://nodejs.org)) и затем пришлёт ссылку и код снова. Другим способом помощник ключ не передаёт: так ключ попадает в проект, минуя чат.

## Как перевести организацию в рабочий режим с помощником?

Так же, как ключ: по ссылке и коду от помощника. Когда проверки в песочнице пройдены, анкета одобрена, кассир подключён и тариф оплачен, помощник пришлёт ссылку и код. Откройте ссылку, сверьте код, посмотрите, что изменится, и подтвердите перевод кнопками на экране. Не совпадает код или вы ничего не просили — нажмите **«Это не я»**. Кассира, анкету и оплату помощник не трогает: если экран попросит их, сделайте это сами по ссылкам на экране. После перевода счета настоящие: тестовые счета, ссылки и QR удалятся.

## Как хранить ключи, чтобы ничего не утекло?

Ключ хранится локально в `APIPAY_API_KEY`, секрет уведомлений — в `APIPAY_WEBHOOK_SECRET`. В подключении с помощником через MCP уведомления обязательны: ключ и секрет выпускаются вместе одной кнопкой по ссылке помощника. При ручной настройке секрет нужен, только если подключены уведомления: он выпускается после сохранения адреса (карточка ключа → «Ещё» → «Создать секретный ключ подписи»).

- Не вставляйте ключи в чат, команды терминала или адреса страниц.
- Помощник не должен читать `.env` или выводить его содержимое. Файл ему технически доступен, поэтому это правило, а не защита: если помощник показал ключ или секрет, отзовите этот ключ в кабинете и попросите помощника получить новый — он пришлёт новые ссылку и код; на сервер новые значения перенесите сами.
- Сохраните существующие переменные и не создавайте новый ключ без необходимости: при настройке ключ автоматически не заменяется.
- Если оплату проверяет опрос, не убирайте его и после подключения webhook — он остаётся страховкой. Как настроить уведомления — в [настройке вебхуков](/guides/nastroyka-webhookov-apipay).

## Что ApiPay сохраняет при работе через MCP?

Журнал MCP записывает каждый вызов: когда, какой инструмент, чем закончился, сколько длился и IP-адрес, с которого пришёл запрос. При ошибке записываются её код и название поля, в котором она нашлась, — без того, что было в нём введено. Об ИИ-клиенте записываются название и версия — если клиент есть в нашем списке (Claude Code, Codex, Cursor и другие), иначе просто «другой», — версия протокола MCP и умеет ли клиент задавать вопросы формой или по ссылке. Ещё записываются обезличенный номер сессии, шаг подключения, какие вопросы помощник вам задал, на какие вы ответили, показал ли клиент вопрос формой и что вы сделали: ответили, отказались или закрыли окно, — без ваших ответов. После входа к записи добавляются ваша учётная запись в ApiPay, приложение, которому вы разрешили доступ, организация и обезличенная метка этого доступа.

Тексты ваших запросов, ответы сервиса, адреса страниц, ключи, телефоны, ИИН, данные анкеты и коды из SMS не записываются: из запроса и ответа остаются только служебные отметки — например, выбранная платформа (Laravel, Next.js) и статус подключения.

Записи о вызовах вместе с IP-адресом хранятся до 180 дней, подробности к ним — до 30 дней. Суточная статистика — сколько было вызовов каждого инструмента, с каким итогом и из какого ИИ-клиента — без адресов, сессий и учётных записей хранится до года. Переписка с вашим ИИ-клиентом не собирается.

## Частые вопросы

**Можно ли на вайбкоде сделать свой сервис аналитики по Kaspi?**
Да: помощник по [apipay.kz/for-ai](/for-ai) и [документации API](/docs) напишет сервис, который читает `GET /invoices` и `GET /invoices/stats` вашей организации. В списке видны и продажи через ApiPay, и проведённые в приложении Kaspi Pay (`origin=kaspi`); вторые подтягиваются не сразу и не всегда полностью, поэтому прошедший период перезапрашивайте.

**Обязательно ли подключать MCP?**
Если помощник работает прямо в вашем проекте с терминалом (Claude Code, Codex) — да: без MCP он остановится и попросит подключить его на экране [«Подключить с ИИ»](/setup/ai). Помощнику без терминала (чат в браузере, конструктор сайтов) достаточно инструкции [apipay.kz/SKILL.md](/SKILL.md) и страницы [apipay.kz/for-ai](/for-ai). С MCP помощник ведёт подключение по шагам, а после вашего входа сам проверяет песочницу и готовит выход в рабочий режим.

**Нужен ли кассир, чтобы начать?**
Для песочницы — нет: код можно писать и проверять сразу после регистрации. Кассир и одобренная анкета нужны для настоящих платежей.

**Где взять полный справочник API?**
В [документации](/docs): эндпоинты, поля, коды ошибок. Обзор возможностей — на странице [Kaspi API](/kaspi-api).

---

ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.
База знаний: https://apipay.kz/guides