# Aitole — полный текст для ИИ-ассистентов > Приём оплат в Kaspi Pay поверх собственного аккаунта мерчанта (Казахстан): > постоянные ссылки на оплату, счета на номер, регулярные счета, возвраты, > бот в Telegram и REST API с вебхуками и песочницей. Независимый сервис, > не банк и не партнёр АО «Kaspi Bank». Сайт: https://aitole.kz Файл собран автоматически из markdown-версий страниц. Краткая версия — https://aitole.kz/llms.txt --- # Aitole — оплата в Kaspi без ручной сверки Счёт, постоянная ссылка или регулярный платёж уходят клиенту в Kaspi, а вам сразу приходит «оплачено». Поверх собственного аккаунта мерчанта, фиксированная подписка вместо процента с оборота. ## Как получать оплату - **Постоянная ссылка** `aitole.kz/pay/…` для Instagram, Taplink или закрепа в канале: с телефона открывает Kaspi, с компьютера показывает QR. Сумма фиксированная или клиент вводит сам. Кабинет, Telegram, API. - **Счёт на номер**: перед отправкой видно имя владельца номера. Telegram, API. - **Регулярные счета** раз в неделю, месяц или квартал, с повторами. Кабинет, API. - **Разовая оплата**: ссылка Kaspi на одну покупку. Кабинет, Telegram, API. Оплаты и возвраты видны в кабинете, «Оплачено» приходит в Telegram. Вернуть деньги можно из кабинета, полностью или частично. ## В чём идея У малого бизнеса в Казахстане Kaspi уже есть, а приём платежей делается руками: кассир выставляет счёт в приложении, покупатель платит, кто-то сверяет скриншоты. Aitole убирает ручную часть: счёт уходит из кабинета, Telegram или вашего кода, оплата отмечается сама, сверять нечего. Эквайринг для этого избыточен — договор с банком, проверки, процент с каждого платежа. Aitole работает поверх того Kaspi, который у вас уже есть. ## Чем отличаемся - **Бесплатный тариф на настоящих деньгах.** Не триал: 20 оплаченных платежей в месяц навсегда, без карты. У конкурентов бесплатен только пробный период. - **Считаем оплаченные платежи, а не выставленные счета.** Брошенный покупателем счёт квоту не расходует. - **Песочница повторяет боевой путь целиком**, включая задержку поллера. Проверяете тот же код, который пойдёт на живых деньгах. - **Сообщаем, когда приём встал.** Сессия Kaspi умирает регулярно — от входа в приложение под тем же номером. Мы пишем об этом в Telegram и показываем в кабинете, а не ждём, пока вы заметите по отсутствию платежей. - **Несколько Kaspi-касс в одном аккаунте**, с привязкой ключа к кассе. ## Тарифы | тариф | цена в месяц | оплаченных платежей | |---|---|---| | Free | 0 ₸ | 20 | | Start | 7 000 ₸ | 500 | | Pro | 30 000 ₸ | без лимита | Комиссию за приём Kaspi удерживает сам, по вашему договору с ним. Мы к ней ничего не добавляем и на её размер не влияем. ## Что нужно для старта Аккаунт Kaspi Pay для бизнеса и отдельный номер сотрудника с ролью «Кассир». Подключение занимает пару минут: номер и код из SMS. Песочница доступна сразу, до подключения Kaspi. ## Честно о рисках Aitole — независимый сервис, не банк и не партнёр АО «Kaspi Bank». Деньги идут напрямую на ваш Kaspi-счёт, мы их не касаемся и вывести не можем: роль «Кассир» этого не умеет. У Kaspi одна активная сессия на номер. Пока номер отдан платформе, входить под ним в приложение Kaspi Pay нельзя — иначе приём платежей встанет до повторного входа по SMS. ## Дальше - [Справочник API](https://aitole.kz/docs/) · [он же в markdown](https://aitole.kz/docs/index.md) - [Плейбук для ИИ-агента](https://aitole.kz/for-ai/) - [Кабинет](https://aitole.kz/dashboard/) Вопросы и поддержка: [hello@aitole.kz](mailto:hello@aitole.kz). --- # Как сделать ссылку на оплату Kaspi для Instagram и Taplink > В самом Kaspi Pay ссылку на оплату дают в мобильном POS, в разделе «Удалённая оплата»: сумму вводит покупатель, а оплаты продавец сверяет сам. Постоянная ссылка Aitole вида aitole.kz/pay/… работает поверх вашего Kaspi Pay: сумма фиксированная или свободная, с телефона открывается приложение Kaspi, с компьютера — QR, а каждая оплата приходит вам с суммой и названием ссылки в кабинет и Telegram. Деньги поступают напрямую на ваш Kaspi. Источник: https://aitole.kz/kaspi-ssylka-na-oplatu/ · Aitole — https://aitole.kz ## Два способа дать клиенту ссылку на оплату | | Ссылка из Kaspi Pay | Постоянная ссылка Aitole | |---|---|---| | Где создаётся | Мобильный POS → «Удалённая оплата» → «Ссылка для оплаты» | Кабинет Aitole, Telegram-бот или API | | Сумма | Вводит покупатель | Фиксированная или свободная, с минимумом и максимумом | | Что видит клиент | Переход в приложение Kaspi | Страница с названием товара и суммой: с телефона — сразу Kaspi, с компьютера — QR | | Как узнать об оплате | Уведомление в мобильном POS у кассира | Уведомление в Telegram, запись в кабинете, вебхук для вашей системы | | Сколько ссылок | Одна на точку продаж | Сколько угодно: под каждую услугу, товар или пост | | Стоимость | Входит в Kaspi Pay | 20 оплат в месяц бесплатно, дальше — фиксированный тариф | Штатная ссылка Kaspi Pay подходит, если товаров мало и сверять оплаты руками не трудно. Постоянная ссылка Aitole нужна, когда хочется отдельную ссылку под каждую услугу с правильной суммой и не искать, кто и за что заплатил. ## Как сделать постоянную ссылку за пару минут 1. Зарегистрируйтесь на [aitole.kz](/) через Google — сразу откроется кабинет с песочницей. 2. Подключите свой Kaspi Pay: добавьте в приложении Kaspi Pay сотрудника с ролью «Кассир» и введите код из SMS. Пароль от Kaspi не нужен. 3. Создайте ссылку в кабинете → «Ссылки на оплату»: название («Консультация, 60 минут»), сумма или «клиент вводит сам». Или напишите боту в Telegram: `ссылка 4990 Консультация`. 4. Вставьте ссылку в шапку профиля Instagram, кнопку Taplink, закреп в Telegram-канале или пришлите клиенту в директ. ## Что видит покупатель Покупатель открывает ссылку и видит название товара или услуги, сумму и кнопку «Оплатить в Kaspi». С телефона кнопка сразу открывает приложение Kaspi с этой суммой — остаётся подтвердить оплату. С компьютера страница показывает QR, который сканируют телефоном. QR в Kaspi живёт пять минут, поэтому страница создаёт свежий при каждом нажатии: ссылка не устаревает, сколько бы она ни висела в профиле. По желанию на странице есть поле «Ваше имя». По QR Kaspi не сообщает продавцу, кто заплатил, а с именем вы сразу узнаете оплату. ## Как вы узнаёте об оплате - В Telegram приходит «✅ Оплачено 4 990 ₸ · Ссылка „Консультация“» — с именем, если клиент его оставил. - В кабинете у каждой ссылки видно число оплат и сумму. - Если у вас есть сайт или CRM, туда приходит вебхук `payment.paid` — заказ отмечается оплаченным без участия человека. ## Что важно знать - Деньги идут напрямую на ваш счёт Kaspi Pay. Aitole их не касается: роль «Кассир» в Kaspi не умеет выводить деньги. - Нужен Kaspi Pay для бизнеса — тот, через который вы уже принимаете QR. - Комиссию за приём оплаты Kaspi удерживает сам, по вашему договору с ним. Aitole к ней ничего не добавляет. - Кассовый чек по-прежнему выдаёт ваша онлайн-касса или Kaspi Касса — ни ссылка Kaspi Pay, ни Aitole его не пробивают. ## Вопросы ### Сколько стоит постоянная ссылка на оплату? Ссылки бесплатны и не ограничены по количеству. Платите вы только за оплаченные платежи сверх 20 в месяц: тариф Start — 7 000 ₸ в месяц за 500 оплат. Процента с оборота нет. ### Можно ли сделать ссылку, где клиент сам вводит сумму? Да. При создании выберите «Клиент вводит» и при желании задайте минимум и максимум — например, для донатов, предоплаты или оплаты по договорённости. ### Нужен ли сайт, чтобы принимать оплату по ссылке? Нет. Страница оплаты живёт на aitole.kz, вам достаточно поставить ссылку в профиль или прислать в переписке. ### Куда приходят деньги? На ваш счёт Kaspi Pay, как при обычной оплате по QR. Aitole только выставляет QR от имени вашей кассы и видит, что оплата прошла. ### Ссылка перестанет работать через пять минут, как QR? Нет. Пять минут живёт QR, который создаётся при нажатии «Оплатить». Сама ссылка постоянная, пока вы её не выключите в кабинете. --- # Как автоматически выставлять счёт Kaspi на номер клиента > Счёт на номер приходит клиенту прямо в приложение Kaspi, и он оплачивает его в одно касание. В Kaspi Pay такой счёт кассир выставляет вручную. Aitole делает это автоматически: одним сообщением боту в Telegram («4990 +7 701 … комментарий»), из вашего сайта или CRM по API или по расписанию — раз в неделю, месяц или квартал. Перед отправкой видно имя владельца номера из Kaspi, а об оплате приходит уведомление. Источник: https://aitole.kz/kaspi-schet-na-nomer/ · Aitole — https://aitole.kz ## Когда нужен счёт на номер, а когда ссылка - **Счёт на номер** — когда вы знаете покупателя: записался на услугу, оформил заказ в директе, продлевает абонемент. Счёт сам появляется у него в Kaspi, ничего пересылать не надо. - **Ссылка или QR** — когда покупатель вам ещё не знаком: ссылка в профиле Instagram, QR на кассе. Подробнее — в статье о [ссылке на оплату Kaspi](/kaspi-ssylka-na-oplatu/). ## Три способа выставить счёт без ручной работы ### Из Telegram одним сообщением Подключите бота в кабинете и напишите ему сумму, номер и комментарий в любом порядке: `4990 +77011234567 Маникюр`. Бот спросит у Kaspi, чей это номер, и покажет: «Счёт 4 990 ₸ для Сауле К. — выставить?». Опечатка в номере ловится до того, как счёт уйдёт чужому человеку. ### Из сайта или CRM по API Один запрос `POST /v2/invoices` с номером и суммой — и счёт у клиента в Kaspi. Об оплате ваша система узнаёт вебхуком `payment.paid` с подписью. Есть песочница: весь путь можно проверить без настоящих денег. Подробно — в [справочнике API](/docs/). ### Регулярно, по расписанию Для абонементов и подписок: укажите номер, сумму и период — неделя, месяц или квартал. Счёт уходит сам в выбранный день; если клиент не оплатил, Aitole повторит и сообщит вам. ## Что происходит после отправки | Статус | Что это значит | |---|---| | Ждёт оплаты | Счёт у клиента в Kaspi | | Оплачен | Деньги на вашем счёте Kaspi Pay, вам пришло уведомление | | Отклонён | Клиент отказался от счёта в приложении Kaspi | | Истёк | Клиент не оплатил: счёт Kaspi живёт около суток | Оплаченный счёт можно вернуть — полностью или частично — из кабинета или по API. ## Что важно знать - Номер должен быть зарегистрирован в Kaspi: иначе счёт не придёт, и бот предупредит об этом заранее. - Деньги идут напрямую на ваш Kaspi Pay. Aitole подключается через штатную роль «Кассир», которая не умеет выводить деньги. - Тарифы считают только оплаченные счета: выставленные и неоплаченные лимит не тратят. ## Вопросы ### Клиент увидит, что счёт выставлен через Aitole? Нет. Счёт приходит от вашей торговой точки в Kaspi, как если бы его выставил ваш кассир. ### Можно выставить счёт на номер без сайта и программиста? Да, через Telegram-бота: одно сообщение с суммой и номером. Сайт и API нужны, только если счета должна выставлять ваша система сама. ### Сколько живёт счёт Kaspi на номер? Около суток. Если клиент не успел, выставьте новый; для регулярных счетов Aitole повторяет сам. ### Сколько это стоит? 20 оплаченных счетов в месяц — бесплатно навсегда. Дальше тариф Start: 7 000 ₸ в месяц за 500 оплат. Комиссию Kaspi удерживает сам, по вашему договору. ### Видно ли, кто оплатил? Да. Перед отправкой Aitole показывает имя владельца номера из Kaspi, и это имя приходит в уведомлении об оплате. --- # Как принимать оплату через Kaspi без сайта и эквайринга > Для приёма оплаты через Kaspi не нужны ни сайт, ни договор эквайринга, ни терминал — достаточно Kaspi Pay для бизнеса, его открывают онлайн за несколько минут. Принимать можно по QR, по ссылке и счётом на номер прямо из приложения Kaspi Pay, но тогда каждую оплату вы сверяете сами. Сервисы поверх Kaspi Pay, такие как Aitole, добавляют постоянные ссылки для Instagram, счета из Telegram и регулярные счета — и отмечают оплату сами. Источник: https://aitole.kz/oplata-kaspi-bez-saita/ · Aitole — https://aitole.kz ## Что нужно на самом деле - **Kaspi Pay для бизнеса.** По справочнику Kaspi, открыть счёт Kaspi Pay можно онлайн за 5 минут. Если вы уже принимаете оплату по Kaspi QR — он у вас есть. - **Способ показать клиенту, что и сколько оплатить.** QR, ссылка или счёт на номер. - **Чек.** Фискальный чек по-прежнему обязателен: его выдаёт онлайн-касса или Kaspi Касса. Принимает ли деньги сайт или переписка — неважно. Сайт и эквайринг нужны для оплаты картами любых банков на собственной странице. Чтобы просто принимать деньги в Kaspi, ни то ни другое не требуется. ## Способы принимать оплату без сайта | Способ | Как это выглядит | Подходит для | |---|---|---| | Kaspi QR на кассе | Клиент сканирует QR в магазине или на точке | Офлайн-продаж | | Ссылка из Kaspi Pay | Ссылка точки продаж, сумму вводит клиент | Переписки, редких оплат | | Счёт на номер из Kaspi Pay | Кассир выставляет счёт в приложении вручную | Знакомых клиентов, небольшого потока | | Постоянная ссылка Aitole | aitole.kz/pay/… с суммой и названием, оплата отмечается сама | Instagram, Taplink, Telegram-канала | | Счёт на номер из Telegram | Одно сообщение боту — счёт у клиента в Kaspi | Записи на услуги, заказов в директе | | Регулярные счета | Счёт сам уходит раз в неделю, месяц или квартал | Абонементов, курсов, подписок | ## Где начинается ручная работа Пока оплат несколько в неделю, штатных инструментов Kaspi Pay достаточно. Когда их становится 20–100 в месяц, появляются три проблемы: - **Сверка.** Нужно понять, кто из клиентов заплатил, за что и сколько. Клиенты присылают скриншоты, вы ищете оплату в истории. - **Счета руками.** Каждый счёт на номер — это открыть приложение, вбить номер, сумму, комментарий. - **Повторяющиеся платежи.** Абонементы приходится напоминать и выставлять заново каждый месяц. Aitole решает их поверх вашего же Kaspi Pay: оплата отмечается сама, с суммой и названием, а уведомление приходит в Telegram. Подключение — через штатную роль «Кассир» и код из SMS, без договора с банком. ## Сколько это стоит - Kaspi удерживает свою комиссию за приём оплаты по вашему договору — она одинакова, принимаете вы оплату вручную или через сервис. - Aitole: 20 оплаченных платежей в месяц бесплатно и навсегда; 500 оплат — 7 000 ₸ в месяц; без ограничения — 30 000 ₸. Процента с оборота нет. ## Вопросы ### Можно ли принимать оплату через Kaspi, если я самозанятый или ИП без сайта? Сайт для этого не нужен. Нужен Kaspi Pay для бизнеса; условия подключения для вашей формы бизнеса уточните в Kaspi Гид или на pay.kaspi.kz. ### Нужен ли договор эквайринга? Нет. Эквайринг нужен для приёма карт любых банков на собственной странице оплаты. Оплата в Kaspi проходит внутри приложения Kaspi и зачисляется на ваш Kaspi Pay. ### Нужно ли пробивать чек, если клиент оплатил по ссылке или счёту? Да, как и при любой оплате. Чек выдаёт ваша онлайн-касса или Kaspi Касса — её подключают в Kaspi Pay. ### Чем Aitole отличается от ссылки из самого Kaspi Pay? В ссылке Kaspi Pay сумму вводит клиент, а оплаты вы сверяете сами. В Aitole под каждую услугу — своя ссылка с суммой, счета на номер и регулярные счета выставляются автоматически, а об оплате приходит уведомление с названием и именем. ### Безопасно ли давать сервису доступ к Kaspi Pay? Доступ выдаётся через штатную роль «Кассир»: она выставляет счета и видит их статус, но не умеет выводить деньги, видеть баланс и менять настройки. Пароль от Kaspi не нужен. --- # Как принимать регулярные платежи и абонементы через Kaspi > Списать деньги с клиента по подписке без его подтверждения через Kaspi нельзя — поэтому регулярный платёж в Kaspi устроен как регулярный счёт. Aitole сам выставляет счёт на номер клиента раз в неделю, месяц или квартал в выбранный день и час; клиент получает его в приложении Kaspi и оплачивает в одно касание. Если не оплатил — счёт уходит повторно, а вам приходит сообщение. Деньги идут напрямую на ваш Kaspi Pay. Источник: https://aitole.kz/kaspi-regulyarnye-platezhi/ · Aitole — https://aitole.kz ## Кому это нужно - Студиям и фитнес-клубам с месячными абонементами. - Курсам, репетиторам, школам — оплата за месяц или четверть. - Подпискам на сервисы, клубам по интересам, аренде. - Всем, кто сейчас каждый месяц пишет клиентам «напоминаю про оплату» и выставляет счета вручную. ## Как это работает 1. Вы создаёте регулярный счёт: номер клиента, сумма, период (неделя, месяц или квартал), день и время. Например: «4 990 ₸ каждое 5-е число в 10:00». 2. В этот день Aitole выставляет счёт на номер клиента — он приходит прямо в приложение Kaspi. 3. Клиент оплачивает в одно касание. Вам приходит «✅ Оплачено · Регулярный счёт · платёж 3». 4. Не оплатил — через заданный интервал счёт уходит снова. Когда повторы исчерпаны, вам приходит сообщение, и вы решаете, что делать с клиентом. Если первый месяц клиент уже оплатил, первый счёт придёт через период. Если нужно сразу — включите «выставить сейчас». ## Что можно настроить | Настройка | Варианты | |---|---| | Период | Неделя, месяц, квартал | | День | День недели или число месяца; «последний день месяца» | | Время | В течение дня, по Алматы | | Повторы при неоплате | Число попыток и интервал между ними | | Число платежей | Без ограничения или ровно N — например, курс из 3 месяцев | | Пауза | Можно приостановить и возобновить, например на время отпуска клиента | Управлять можно из кабинета или по API, если подписки живут в вашей системе. ## Что важно знать - Каждый платёж клиент подтверждает сам — это обычный счёт Kaspi, а не автосписание с карты. - Номер телефона клиента для регулярных счетов хранится зашифрованным, в кабинете виден только маской. - Счёт Kaspi живёт около суток: если клиент не оплатил его вовремя, сработают повторы. - Тариф считает только оплаченные счета: 20 в месяц бесплатно, дальше 7 000 ₸ в месяц за 500. ## Вопросы ### Можно ли списывать абонентскую плату через Kaspi автоматически, без участия клиента? Нет. Через Kaspi каждый платёж клиент подтверждает в приложении. Регулярные счета делают это максимально простым: счёт приходит сам, оплата — одно касание. ### Что будет, если клиент не оплатит? Счёт выставится повторно по вашим настройкам. Когда попытки закончатся, вы получите сообщение в Telegram, а регулярный счёт остановится или подождёт следующего периода — как вы настроили. ### Клиент может отказаться от подписки? Да. Если он отклонит счёт в приложении Kaspi, регулярный счёт отменится, и вы получите сообщение «Клиент отказался». ### Можно ли сделать оплату за курс из трёх месяцев? Да, укажите число платежей — 3. После третьей оплаты регулярный счёт завершится сам. ### Сколько это стоит? Регулярные счета входят во все тарифы. Платите только за оплаченные счета сверх 20 в месяц: тариф Start — 7 000 ₸ за 500 оплат. --- # Как принимать оплату Kaspi через Telegram > Есть два сценария. Если вы продаёте сами — бот Aitole выставляет счёт Kaspi на номер клиента, одноразовую или постоянную ссылку на оплату одним сообщением («4990 +7 701 … маникюр») и присылает «✅ Оплачено» с суммой и именем. Если у вас свой Telegram-бот — он подключается к Aitole по API: выставляет счёт или QR одним запросом и узнаёт об оплате вебхуком. В обоих случаях деньги идут напрямую на ваш Kaspi Pay. Источник: https://aitole.kz/kaspi-telegram-bot/ · Aitole — https://aitole.kz ## Бот Aitole: оплата из переписки за 10 секунд Подключите Telegram в кабинете Aitole (раздел «Уведомления») — и пишите боту обычным текстом: | Сообщение | Что сделает бот | |---|---| | `4990 +77011234567 Маникюр` | Покажет имя владельца номера из Kaspi и после подтверждения выставит счёт — он придёт клиенту в Kaspi | | `5000 кофе` | Пришлёт ссылку Kaspi на оплату — её можно переслать клиенту; QR в Kaspi живёт 5 минут | | `ссылка 4990 Консультация` | Создаст постоянную ссылку aitole.kz/pay/… для профиля или закрепа | | `ссылка Донат` | Постоянная ссылка, где сумму вводит клиент | Сумма, номер и комментарий — в любом порядке, номер с пробелами и скобками тоже понимается. ## Уведомления об оплате Каждая оплата приходит сообщением: сумма, касса, способ (QR или счёт на номер), имя клиента, если оно известно, и комментарий. Отдельно — красное предупреждение, если Kaspi остановил приём платежей по кассе: обычно это значит, что под номером кассира вошли в приложение Kaspi Pay. ## Свой Telegram-бот с оплатой Kaspi Если у вас бот для записи, заказов или доступа к закрытому каналу, оплату к нему подключают через API Aitole: 1. Бот получает от клиента номер телефона и вызывает `POST /v2/invoices` — счёт уходит клиенту в Kaspi. Или `POST /v2/qr` — бот присылает ссылку на оплату. 2. Когда клиент оплатил, Aitole шлёт вебхук `payment.paid` с подписью — бот выдаёт доступ, подтверждает запись или отправляет заказ. 3. Всё можно проверить в песочнице без настоящих денег. Подробно — в [справочнике API](/docs/). Если бот пишет ИИ-ассистент, дайте ему [инструкцию для ИИ](/for-ai/). ## Что важно знать - Бот выставляет счета только с боевой кассы и только в личном чате с вами — в группах он не принимает команды на оплату. - Перед счётом на номер бот спрашивает подтверждение: опечатка в номере не уйдёт чужому человеку. - Кассовый чек выдаёт ваша онлайн-касса или Kaspi Касса — бот его не пробивает. ## Вопросы ### Можно ли принимать оплату Kaspi прямо в Telegram без сайта? Да. Бот Aitole выставляет счёт или ссылку из переписки, клиент оплачивает в приложении Kaspi, вам приходит уведомление. Сайт не нужен. ### Как подключить оплату Kaspi к своему Telegram-боту? Через REST API Aitole: бот выставляет счёт или QR одним запросом и получает вебхук об оплате. Есть песочница и готовый промпт для ИИ-ассистента. ### Будут ли приходить уведомления, если счёт выставлен не через бота? Да. Уведомления приходят обо всех оплатах кассы — из кабинета, по ссылке, по API и регулярных счетов. ### Почему бот не выставляет счета в группе? Команды на выставление счетов бот принимает только в личном чате с тем, кто подключил его в кабинете. Так счёт не выставит случайный участник группы. ### Сколько стоит? Бот бесплатный. Платите только за оплаченные платежи сверх 20 в месяц: тариф Start — 7 000 ₸ в месяц за 500 оплат. --- # Есть ли API Kaspi Pay для сайта и CRM > Открытого публичного API для приёма платежей у Kaspi Pay нет: «Платежи на Kaspi.kz» подключают по заявке через Kaspi Гид, а API Магазина на Kaspi.kz работает с товарами и заказами маркетплейса, а не с оплатой. Сервисы поверх Kaspi Pay дают обычный REST API. В Aitole один запрос выставляет QR или счёт на номер, оплата приходит вебхуком с подписью HMAC-SHA256, а весь путь можно проверить в песочнице без настоящих денег. Источник: https://aitole.kz/kaspi-api/ · Aitole — https://aitole.kz ## Какие есть варианты | Вариант | Что это | Кому подходит | |---|---|---| | «Платежи на Kaspi.kz» | Партнёрство с Kaspi: ваши услуги в приложении Kaspi.kz, подключение по заявке, ответ — в течение нескольких дней | Крупным поставщикам услуг | | API Магазина на Kaspi.kz | Товары, остатки и заказы маркетплейса Kaspi | Продавцам на маркетплейсе | | Сервис поверх Kaspi Pay (Aitole) | REST API к вашей кассе Kaspi Pay: QR, счета, ссылки, возвраты, вебхуки | Сайтам, CRM, ботам, SaaS | ## Как устроен API Aitole ``` POST https://api.aitole.kz/v2/invoices X-API-Key: sk_live_… Idempotency-Key: order-42 {"amount": 4990, "phone": "+77011234567", "comment": "Заказ №42"} ``` - `POST /v2/qr` — QR и ссылка на оплату для одной покупки. - `POST /v2/invoices` — счёт на номер клиента, придёт ему в приложение Kaspi. - `POST /v2/refunds` — возврат, полный или частичный. - Постоянные ссылки на оплату и регулярные счета — тоже через API. - `GET /v2/events` — журнал событий: если вебхук не дошёл, ничего не теряется. - Вебхуки `payment.paid`, `payment.expired`, `payment.refunded` с подписью HMAC-SHA256. Полное описание — в [справочнике API](/docs/), markdown-версия — [docs/index.md](/docs/index.md). ## Что обычно ломается в самописной интеграции — и как это закрыто - **Двойной счёт при повторе запроса.** Заголовок `Idempotency-Key`: повтор с тем же ключом вернёт тот же счёт. - **Отказ Kaspi.** Приходит с HTTP 200 и `status: "failed"` и понятной причиной — не нужно гадать по кодам. - **Сессия Kaspi умерла.** Kaspi держит одну сессию на номер; если кассир вошёл в приложение под тем же номером, приём встаёт. Aitole шлёт событие и сообщение в Telegram. - **Несколько касс.** Ключ можно привязать к конкретной кассе, чтобы платежи проекта не ушли на соседнюю. ## Песочница Тестовый ключ `sk_test_…` выдаётся при регистрации. Счета в песочнице не уходят в Kaspi, а статус «оплачено» ставится кнопкой или запросом — проверяется весь путь вашего кода, включая вебхуки. ## Если интеграцию пишет ИИ Дайте ассистенту ссылку на [инструкцию для ИИ](/for-ai/) или полный текст [llms-full.txt](/llms-full.txt) — там справочник, правила и готовый промпт. ChatGPT, Claude или Cursor соберут интеграцию по ним без догадок об эндпоинтах. ## Вопросы ### Есть ли у Kaspi Pay официальный публичный API для приёма платежей? Публичного API с самостоятельной регистрацией нет. Партнёрство «Платежи на Kaspi.kz» подключают по заявке через Kaspi Гид. Для сайтов и CRM используют сервисы поверх Kaspi Pay. ### Деньги проходят через Aitole? Нет. Счёт выставляется от имени вашей кассы, клиент платит в Kaspi, деньги зачисляются на ваш Kaspi Pay. Aitole видит только статус оплаты. ### Как подключить мою кассу Kaspi к API? В кабинете: добавьте в Kaspi Pay сотрудника с ролью «Кассир» и введите код из SMS. Пароль от Kaspi не нужен, роль «Кассир» не умеет выводить деньги. ### Сколько стоит API? API входит во все тарифы, включая бесплатный: 20 оплаченных платежей в месяц. Start — 7 000 ₸ за 500 оплат, Pro — 30 000 ₸ без ограничения. Запросы и неоплаченные счета не тарифицируются. ### Можно ли проверить интеграцию без настоящих денег? Да, в песочнице с тестовым ключом: счета не уходят в Kaspi, а оплату вы отмечаете сами. --- # Нужен ли кассовый чек при оплате через Kaspi > Да — фискальный чек нужен за любую продажу, в том числе при оплате через Kaspi QR, счёт на номер или ссылку. Проще всего подключить Kaspi Касса в приложении Kaspi Pay: по справочнику Kaspi, за оплату по Kaspi QR, Kaspi Gold и удалённую оплату покупатель получает фискальный чек прямо в приложении Kaspi.kz. Без Kaspi Касса чек выдаёт ваша онлайн-касса. Сервисы вроде Aitole выставляют счета, но чек не пробивают. Источник: https://aitole.kz/chek-pri-oplate-kaspi/ · Aitole — https://aitole.kz > Это не налоговая консультация. Правила зависят от вашего налогового режима и вида деятельности — точный ответ даст бухгалтер или справка Kaspi для вашего случая. ## Коротко | Как принимаете оплату | Нужен ли чек | Кто его выдаёт | |---|---|---| | Kaspi QR, счёт или ссылка, Kaspi Касса подключена | Да, формируется автоматически | Kaspi Касса — чек приходит покупателю в Kaspi.kz | | Kaspi QR, счёт или ссылка, Kaspi Касса не подключена | Да | Ваша онлайн-касса (ККМ) | | Наличные или карта другого банка | Да | Kaspi Касса или онлайн-касса | ## Что такое Kaspi Касса По справочнику Kaspi, Kaspi Касса — это сервис в мобильном приложении Kaspi Pay, который формирует фискальные чеки и автоматически передаёт данные о них в налоговые органы. Отдельный кассовый аппарат и его обслуживание при этом не нужны. За оплату по Kaspi QR, Kaspi Gold и удалённую оплату покупатель получает чек в приложении Kaspi.kz; за наличные и карты других банков можно отправить ссылку на чек по SMS. На семинаре НПП «Атамекен» представители налоговых органов разъясняли для ИП на упрощённой декларации: при подключённой Kaspi Касса операции по QR и карте фискализируются автоматически и отдельно пробивать чек ККМ не нужно; без неё — нужна отдельная онлайн-касса. ## А если счета выставляет Aitole Aitole выставляет счета и QR от имени вашей кассы Kaspi Pay — для Kaspi это обычная оплата по QR или удалённая оплата вашей торговой точки. Поэтому правила те же: - подключена Kaspi Касса — она работает так же, как при оплате, выставленной вручную; - нет Kaspi Касса — чек выдаёт ваша онлайн-касса, как и раньше. Сам Aitole фискальные чеки не формирует и в ОФД данные не передаёт. ## Источники - [Справочник Kaspi: Kaspi Касса](https://guide.kaspi.kz/partner/ru/kaspi_kassa/conditions/q2334) - [Finratings: «Kaspi Pay не всегда заменяет онлайн-кассу» (ноябрь 2025)](https://finratings.kz/news/9037-kaspi-pay-ne-vsegda-zameniaet-onlain-kassu-chto-dolzhny-znat-ip/) ## Вопросы ### Нужно ли пробивать чек, если клиент оплатил по Kaspi QR? Да. С подключённой Kaspi Касса чек формируется автоматически и приходит покупателю в приложение Kaspi.kz. Без неё чек выдаёт ваша онлайн-касса. ### А если клиент оплатил счёт на номер или по ссылке? Это удалённая оплата — чек тоже нужен. По справочнику Kaspi, за удалённую оплату с подключённой Kaspi Касса покупатель получает чек в приложении Kaspi.kz. ### Сколько стоит Kaspi Касса? Kaspi пишет, что подключение бесплатное и онлайн, а отдельный кассовый аппарат не нужен. Условия по чекам за наличные и карты других банков уточните в справочнике Kaspi. ### Пробивает ли Aitole чеки? Нет. Aitole выставляет счета и отслеживает оплату. Чек выдаёт Kaspi Касса или ваша онлайн-касса — как и при оплате, выставленной вручную. ### Можно не пробивать чек, если оплата пришла переводом на Kaspi Gold? Приём оплаты за товары и услуги переводом на личную карту — отдельный вопрос с налоговыми рисками. Для бизнеса принимайте оплату через Kaspi Pay и выдавайте чек; детали уточните у бухгалтера. --- # Как автоматизировать приём оплаты Kaspi — все способы > Есть пять путей. Штатные инструменты Kaspi Pay — QR, ссылка и счета из приложения — бесплатны, но оплаты сверяются вручную. «Платежи на Kaspi.kz» — официальное партнёрство по заявке, для крупных поставщиков услуг. Сервисы поверх Kaspi Pay — Aitole, ApiPay, Tole, darPAY, AiPay — подключаются через роль «Кассир» и дают API, ссылки и автоматические счета; цены от 0 до 25 000 ₸ в месяц или процент с оборота. Интеграции для CRM и учёта — KPAY для Bitrix24 и amoCRM, SmartPay для МоегоСклада. И свой сервер на открытом kaspi-pos-automation от Tapter — бесплатно, но с поддержкой своими силами. Источник: https://aitole.kz/sravnenie/ · Aitole — https://aitole.kz > Цены и условия — с сайтов сервисов на 15.10.2026. Они меняются: перед выбором проверьте актуальные на сайте сервиса. Aitole — один из сервисов в этом обзоре. ## 1. Штатные инструменты Kaspi Pay Kaspi Pay для бизнеса уже даёт всё, чтобы принимать оплату без сайта и эквайринга: Kaspi QR на кассе, ссылку для оплаты в мобильном POS («Удалённая оплата» — сумму вводит покупатель), счёт на номер клиента из приложения и Kaspi Касса для фискальных чеков. **Подходит,** когда оплат немного. **Ограничение:** каждую оплату нужно сверять вручную — кто, за что и сколько заплатил, — а счета выставлять руками. ## 2. «Платежи на Kaspi.kz» Официальное партнёрство Kaspi: ваши услуги появляются в приложении Kaspi.kz. Подключение — по заявке через Kaspi Гид, менеджер Kaspi отвечает в течение нескольких дней. Подходит крупным поставщикам услуг; открытого API с самостоятельной регистрацией у Kaspi Pay нет. ## 3. Сервисы поверх Kaspi Pay Подключаются к вашему же Kaspi Pay через отдельного сотрудника с ролью «Кассир» и код из SMS. Деньги идут напрямую на ваш счёт Kaspi Pay, комиссию Kaspi удерживает по вашему договору. Все перечисленные — независимые сервисы, не партнёры АО «Kaspi Bank». | Сервис | Цена | Что считает лимит | Бесплатно | Чем выделяется | |---|---|---|---|---| | Aitole | 0 ₸ — 20 оплат в месяц; 7 000 ₸ — 500; 30 000 ₸ — без ограничения | Оплаченные платежи за месяц | 20 оплат в месяц навсегда | Telegram-бот для счетов и ссылок, постоянные ссылки aitole.kz/pay, регулярные счета, сайт и справочник на казахском | | ApiPay | 10 000 ₸ — до 30 счетов в сутки; 25 000; 60 000; 90 000 ₸ — до 600 | Счета через API за сутки | Пробный период 3 дня | Каталог товаров и корзина, фискальные чеки через Kaspi ОФД, до 10 менеджеров | | Tole | 9 000 ₸ — до 1 000 счетов; 22 500; 50 000; 80 000 ₸ — до 20 000 | Число счетов | Не указано | OpenAPI, подписки, чеки ОФД; разработчик — Qazaqsoft | | darPAY | 4 % → 1 % с оборота без абонплаты, или 10 000 ₸ — 500 успешных платежей и 20 ₸ за каждый сверху | Оборот или успешные платежи | 30 платежей за 3 дня | amoCRM, Bitrix24, Tilda, JS-виджет | | AiPay | 25 000 ₸ за терминал в месяц при оплате за 3 месяца, без лимита | — | 7 дней | Для салонов, медцентров, ресторанов; опционально — чеки через кассовые сервисы | **Общее ограничение всех таких сервисов:** у Kaspi одна активная сессия на номер. Если под номером кассира войти в приложение Kaspi Pay, сессия сервиса обрывается и приём встаёт до повторного входа по SMS. Спросите, как сервис сообщает об этом: Aitole, например, присылает тревогу в Telegram. ## 4. Интеграции для CRM и учёта | Сервис | Для чего | Цена | Бесплатно | |---|---|---|---| | KPAY | Счета Kaspi из сделок в Bitrix24 и amoCRM; авторизация через Kaspi Платежи, нужен Kaspi Business | 18 500 ₸ в месяц, 14 800 ₸ при оплате за год; без лимита | Пробный период: на странице указаны и 14, и 30 дней | | SmartPay (Smart Innovations) | Счета Kaspi из МоегоСклада, регулярные счета, фискализация с кодами НТИН | От 12 000 ₸ в месяц (до 900 счетов) плюс тариф интеграции от 6 000 ₸ | 3 дня | Подходят, если продажи уже ведутся в CRM или МоёмСкладе и счёт должен рождаться из сделки или заказа. ## 5. Свой сервер на открытом коде Команда Tapter выложила открытый [kaspi-pos-automation](https://github.com/tapter-dev/kaspi-pos-automation) — Node.js-сервер с входом кассира по SMS, счетами, QR, возвратами и вебхуками, под лицензией MIT. Его можно развернуть бесплатно, но сервер, сохранность сессий и обновления под изменения Kaspi придётся поддерживать самим. Подробно — на странице [о kaspi-pos-automation](/kaspi-open-source/). Aitole, к слову, построен на его форке. ## Как выбрать - **Мало оплат, нет времени разбираться** — штатный Kaspi Pay. - **Услуги, Instagram, Telegram; хочется начать бесплатно и платить только за оплаченное** — Aitole. - **Нужны каталог, корзина и чеки внутри сервиса** — ApiPay; чеки ОФД заявляет и Tole. - **Продажи в amoCRM или Bitrix24** — darPAY или KPAY. - **Учёт в МоёмСкладе** — SmartPay. - **Безлимитный поток в одной точке с фиксированной ценой** — AiPay или KPAY. - **Есть разработчик и своя инфраструктура, важно всё держать у себя** — открытый kaspi-pos-automation. ## На что смотреть при выборе 1. **Что считает лимит.** Выставленные счета, оплаченные платежи или оборот. Неоплаченные счета в первом случае тоже тратят лимит. 2. **Есть ли бесплатный режим на живых деньгах** или только пробные дни. 3. **Чеки.** Пробивает ли сервис фискальный чек или его выдаёт ваша Kaspi Касса или онлайн-касса. 4. **Что будет, если сессия Kaspi оборвётся,** и как вы об этом узнаете. 5. **Юридическая часть:** есть ли публичная оферта и реквизиты исполнителя. ## Вопросы ### Есть ли официальный способ автоматизировать оплату Kaspi? Официальные — штатные инструменты Kaspi Pay и партнёрство «Платежи на Kaspi.kz» по заявке. Открытого API для приёма платежей с самостоятельной регистрацией у Kaspi Pay нет; сервисы автоматизации работают поверх вашего Kaspi Pay через роль «Кассир». ### Какой сервис самый дешёвый? На входе — Aitole: 20 оплат в месяц бесплатно навсегда, дальше 7 000 ₸ за 500 оплат. Входные платные тарифы остальных сервисов в обзоре — от 9 000 до 25 000 ₸ в месяц, у darPAY есть вариант с процентом от оборота. ### Безопасно ли подключать сторонний сервис к Kaspi Pay? Роль «Кассир» выставляет счета и видит их статус, но не умеет выводить деньги, видеть баланс и менять настройки организации. Деньги идут напрямую на ваш Kaspi Pay. Проверьте у сервиса оферту и реквизиты. ### Можно ли подключить два сервиса к одной кассе? К одному номеру кассира — нет: у Kaspi одна сессия на номер, второй вход вытеснит первый. Для двух сервисов заведите двух кассиров с разными номерами. ### Почему в обзоре нет других сервисов? Мы включили те, чьи условия смогли проверить на их сайтах 15.10.2026. Обзор обновляется — новые сервисы добавляем после проверки их условий. --- # Можно ли подключить Kaspi Pay по API самому — открытый kaspi-pos-automation > Да. Команда Tapter выложила открытый Node.js-сервер kaspi-pos-automation под лицензией MIT: вход кассира по SMS, счета на номер, QR, возвраты и вебхуки с подписью. Его можно бесплатно развернуть на своём сервере. Цена — инфраструктура и поддержка: сервер, сохранность сессий, слежение за изменениями на стороне Kaspi, мониторинг. Aitole сам построен на форке этого проекта и берёт эту работу на себя. Источник: https://aitole.kz/kaspi-open-source/ · Aitole — https://aitole.kz ## Что это [kaspi-pos-automation](https://github.com/tapter-dev/kaspi-pos-automation) — Express-сервер на Node.js от команды [Tapter](https://tapter.one/kaspi.pos.automation). Он подключается к вашему Kaspi Pay так же, как сервисы автоматизации: через сотрудника с ролью «Кассир» и код из SMS. Код открыт под лицензией MIT — пользоваться, менять и встраивать в свои продукты можно свободно. Что умеет: - вход кассира по номеру телефона и SMS; - счёт клиенту по номеру телефона; - QR для оплаты и отслеживание статуса; - «Единый QR» — оплата из приложений других банков; - история операций, статистика и возвраты; - вебхуки с подписью HMAC-SHA256 и повторами. ## Как запустить 1. Нужен Node.js 20.6 или новее. 2. Склонируйте репозиторий и установите зависимости: `npm install`. 3. Создайте `.env` с ключом `TOKEN_SECRET_KEY` — 64 hex-символа, им шифруются данные сессии. 4. Запустите `npm start` — демо-интерфейс откроется на `localhost:3000`. Сами авторы предупреждают: демо-интерфейс — для проверки API, для боевой кассы нужен свой фронтенд. ## Что придётся поддерживать самим Запустить — полдела. Вот с чем мы столкнулись, когда построили на этом коде свой сервис: - **Сервер 24/7.** Постоянно работающая машина с HTTPS, закрытым доступом к API и бэкапами. Если сервер лёг — платежи не выставляются. - **Сохранность сессий.** Подключённая касса — это сессия, сохранённая на сервере. У нас первое время любой редеплой «разлогинивал» все кассы, пока состояние не вынесли на постоянный диск. - **Изменения на стороне Kaspi.** В сентябре 2026 Kaspi перестал пускать старые сборки приложения — вход кассира начал падать с «Обновите приложение, чтобы войти». В основном репозитории это исправили 28 сентября; кто не следил за обновлениями, неделями не мог подключить кассы. Теперь Aitole распознаёт этот ответ Kaspi: клиент видит понятное сообщение, а нам в ту же минуту приходит тревога — обновление не ждёт жалобы. - **Вытеснение сессии.** У Kaspi одна сессия на номер: стоит кассиру войти в приложение Kaspi Pay — приём встаёт. Нужны мониторинг и тревоги, иначе об этом узнаешь по тишине в кассе. - **Секреты в логах.** Ключи сессии Kaspi не должны попадать в логи и бэкапы в открытом виде. - **Всё вокруг API.** Кабинет для сотрудников, ссылки на оплату для клиентов, регулярные счета, уведомления, сверка, несколько касс — это уже отдельная разработка. ## Своё решение или сервис | | Свой сервер на kaspi-pos-automation | Сервис поверх Kaspi Pay | |---|---|---| | Деньги | Бесплатный код, платите за сервер и время разработчика | Подписка; у Aitole 20 оплат в месяц бесплатно | | Контроль | Полный: код, данные и серверы ваши | Данные у сервиса, код закрыт или частично открыт | | Поддержка | Ваша команда | Сервис: обновления под Kaspi, мониторинг, тревоги | | Время до первого платежа | От дня до недели у разработчика | Минуты | | Для кого | Команды с разработчиком и своей инфраструктурой | Бизнес без разработчика или тот, кто не хочет держать сервер | Если у вас есть разработчик и вам важно, чтобы всё было своё, — берите kaspi-pos-automation. Если нужен результат сегодня и без поддержки сервера — сервис. ## Спасибо Tapter Aitole использует форк kaspi-pos-automation как коннектор к Kaspi. Без открытого кода Tapter наш сервис появился бы намного позже. Наши правки — сохранение сессий на диске, логи без секретов, обновление сборки — лежат в открытом [форке](https://github.com/saygon91/kaspi-pos-automation). ## Вопросы ### Это официальное API Kaspi? Нет. kaspi-pos-automation, как и сервисы автоматизации, работает поверх Kaspi Pay через роль «Кассир» — это не официальная интеграция и не продукт Kaspi. Официальный путь — партнёрство «Платежи на Kaspi.kz» по заявке. ### Это бесплатно? Код — да, лицензия MIT. Платить придётся за сервер и за время того, кто его поддерживает. ### Нужен ли программист? Да. Нужно развернуть сервер, настроить HTTPS и доступ, сделать интерфейс для сотрудников и следить за обновлениями. Без программиста проще взять сервис. ### Чем Aitole отличается от kaspi-pos-automation? Внутри у Aitole — тот же движок подключения к Kaspi. Сверху — инфраструктура и продукт: кабинет, ссылки на оплату для Instagram, Telegram-бот, регулярные счета, тревоги о падении сессии, песочница, несколько касс и поддержка. ### Как следить за изменениями на стороне Kaspi, если развернул сам? Подпишитесь на обновления [репозитория](https://github.com/tapter-dev/kaspi-pos-automation) на GitHub и поставьте мониторинг на вход кассира: если Kaspi снова поднимет требования к приложению, поломка проявится именно там. --- # Справочник Aitole API Базовый адрес: `https://api.aitole.kz` Приём Kaspi Pay по REST поверх аккаунта мерчанта. Все суммы — целые тенге. Время — ISO 8601 в UTC. Тела запросов и ответов — JSON. ## Два контура доступа | контур | заголовок | что делает | |---|---|---| | ключ интеграции | `X-API-Key: sk_live_…` / `sk_test_…` | принимает платежи: `/v2/*` | | токен кабинета | `Authorization: Bearer …` | управляет аккаунтом: `/me/*` | Ключ не управляет кабинетом, токен не двигает деньги. Это разделение обеспечено структурой, а не проверками внутри обработчиков. **Режим ключа жёстко связан с контуром подключения.** `sk_test_` работает только с песочницей, `sk_live_` только с настоящим Kaspi. Попытка смешать даёт `403 key_mode_mismatch`. Поэтому тестовым ключом невозможно списать настоящие деньги. ## Ошибка всегда выглядит одинаково ```json { "error": { "code": "validation_error", "message": "Сумма должна быть целым числом тенге", "category": "permanent", "request_id": "req_0f3c…" } } ``` `category` говорит, что делать: `transient` — повторить, `permanent` — не повторять, `auth` — чинить доступ, `rate_limit` — подождать `Retry-After`. ## Выставить QR ```bash curl -X POST https://api.aitole.kz/v2/qr \ -H "X-API-Key: sk_test_…" \ -H "Idempotency-Key: order-1024" \ -H "Content-Type: application/json" \ -d '{"amount": 5000, "comment": "Заказ №1024"}' ``` Ответ — операция со статусом `pending`, полем `qr_token` (ссылка для покупателя) и `expires_at`. Покажите ссылку клиенту; оплату подтвердит событие, а не этот ответ. **Провайдер может отказать с HTTP 200.** Тогда в ответе придёт `status: "failed"` и `failure_reason` с `failure_message` от Kaspi. Это не ошибка транспорта, проверяйте статус. ## Счёт на номер телефона ```bash curl -X POST https://api.aitole.kz/v2/invoices \ -H "X-API-Key: sk_live_…" \ -H "Idempotency-Key: order-1025" \ -H "Content-Type: application/json" \ -d '{"amount": 12000, "phone": "+77001234567", "comment": "Заказ №1025"}' ``` Покупателю приходит счёт в приложение Kaspi. Номер — в формате E.164; к виду, который ждёт Kaspi, платформа приводит сама. ## Регулярные счета Автосписаний у Kaspi нет — поэтому регулярный платёж здесь это счёт, который сам уходит клиенту по расписанию, а клиент оплачивает его в Kaspi в одно касание. ```bash curl -X POST https://api.aitole.kz/v2/subscriptions \ -H "X-API-Key: sk_live_…" \ -H "Idempotency-Key: sub-client-77" \ -H "Content-Type: application/json" \ -d '{"phone": "+77001234567", "amount": 4990, "period": "month", "billing_day": 5, "description": "Курс, {today}"}' ``` - `period`: `week`, `month` или `quarter`; `billing_day` (неделя 1–7, месяц 1–28) или `billing_day_from_end` (0 — последний день месяца); `billing_time` — «ЧЧ:ММ» по Алматы, 06:00–22:00, по умолчанию 13:00. - Первый счёт: `bill_immediately: true` — сразу, `first_billing_at` — с даты, иначе через период. `total_cycles` — сколько платежей всего. - Не оплатил: повтор `max_retry_attempts` раз (по умолчанию 3) через `retry_interval_hours` (24). Дальше `on_unpaid: "expire"` — льготный период `grace_period_days` (3) и окончание, `"continue"` — следующий период. Открытым всегда остаётся один счёт. - Клиент отклонил счёт в Kaspi — регулярный счёт отменяется сразу (`subscription.cancelled`, `reason: "payer_refused"`). - Касса не принимает платежи — счёт ждёт переподключения, попытка не сгорает. - Номер хранится зашифрованным и возвращается только маской. Номер не клиента Kaspi отвергается сразу: `422 payer_not_kaspi_client`. - Счета подписки — обычные операции с полями `subscription_id`, `subscription_cycle`, `subscription_attempt`. События `subscription.*` — в журнале и вебхуках. ## Постоянные ссылки на оплату QR Kaspi живёт 5 минут, поэтому постоянная ссылка — это страница `aitole.kz/pay/<адрес>`, которая по нажатию «Оплатить» создаёт свежий QR: на телефоне сразу открывается Kaspi, на компьютере показывается QR. ```bash curl -X POST https://api.aitole.kz/v2/payment-links \ -H "X-API-Key: sk_live_…" -H "Content-Type: application/json" \ -d '{"title": "Консультация", "amount": 4990, "merchant_name": "Психолог Айжан"}' ``` - `amount` — фиксированная сумма; без неё клиент вводит сумму сам в пределах `min_amount`/`max_amount`. - `ask_name` (по умолчанию `true`) — спросить имя клиента: по QR Kaspi не сообщает, кто заплатил. Имя попадёт в `payer_name` операции. - `slug` — свой адрес; занят — `409 slug_taken`. Без него адрес строится из названия. - Открытие страницы ничего не создаёт: превью ссылки в мессенджерах не тратят лимит неоплаченных. QR создаётся только нажатием. - Оплата — обычная операция и `payment.paid` с полем `payment_link_id`. `GET /v2/payment-links` отдаёт `paid_count` и `paid_total`, `PATCH` меняет и выключает (`"status": "disabled"`). ## Идемпотентность `Idempotency-Key` обязателен для всех операций, создающих платёж. Повтор с тем же ключом возвращает тот же результат, а не второй счёт. Ключ уникален **в пределах аккаунта**, а не проекта: если два ваших проекта нумеруют заказы независимо, добавьте префикс — `shop-a-1024`, а не `1024`. ## Узнать об оплате Два способа, и лучше оба. **Вебхук** — приходит сам за несколько секунд. ``` POST ваш-адрес X-Webhook-Signature: sha256= Content-Type: application/json {"id":"evt_…","type":"payment.paid","created_at":"…","data":{…}} ``` Подпись — HMAC-SHA256 от строки `"{timestamp}.{сырое тело}"` секретом эндпоинта. Проверяйте её по сырому телу до `JSON.parse`. Свежесть — 300 секунд. Неудачные доставки повторяются через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч; после двух суток непрерывных отказов эндпоинт отключается. **Журнал событий** — `GET /v2/events`, курсорная пагинация. Резерв на случай, когда вебхук не дошёл: история остаётся здесь всегда. Типы событий: `payment.created`, `payment.paid`, `payment.expired`, `payment.cancelled`, `payment.refunded`, `connection.session_expired`, `connection.restored`, `billing.past_due`, `billing.downgraded`. Каждое платёжное событие несёт `connection_id` — через какую кассу прошёл платёж. ## Возврат ```bash curl -X POST https://api.aitole.kz/v2/refunds \ -H "X-API-Key: sk_live_…" \ -H "Idempotency-Key: refund-1024-1" \ -H "Content-Type: application/json" \ -d '{"operation_id": "…", "amount": 5000}' ``` Полный или частичный. Операция остаётся `paid`: возврат ложится поверх платежа, а не отменяет его. Окно — 90 дней. Нужен ключ со scope `refund`. ## Песочница Песочница — это подключение с драйвером `mock`. Настоящий Kaspi не участвует, деньги не двигаются, `qr_token` заведомо ненастоящий. ```bash # довести песочный счёт до оплаты curl -X POST https://api.aitole.kz/v2/sandbox/operations/{id}/pay -H "X-API-Key: sk_test_…" # или просрочить curl -X POST https://api.aitole.kz/v2/sandbox/operations/{id}/expire -H "X-API-Key: sk_test_…" # или «клиент отклонил счёт» curl -X POST https://api.aitole.kz/v2/sandbox/operations/{id}/reject -H "X-API-Key: sk_test_…" # регулярный счёт: следующий шаг сейчас, не дожидаясь даты curl -X POST https://api.aitole.kz/v2/sandbox/subscriptions/{id}/bill-now -H "X-API-Key: sk_test_…" ``` Эти ручки меняют состояние **у провайдера**, а статус вашей операции двигает тот же поллер, что и в бою, с той же задержкой. Вы проверяете ровно тот код, который отработает на живых деньгах. ## Несколько Kaspi-касс У аккаунта может быть несколько боевых подключений. Касса выбирается по порядку: `connection_id` в запросе → касса, к которой привязан ключ → основная касса → единственная активная. Привязка ключа — **граница**, а не умолчание: ключ кассы A не выставит счёт на кассу B, даже если передать её `connection_id`, ответ будет `403 forbidden`. Если активных касс несколько и выбор не сделан — `409 connection_ambiguous`. ## Сессия Kaspi У Kaspi одна активная сессия на номер. Вход в приложение Kaspi Pay под номером кассира вытесняет сессию платформы: подключение уходит в `session_expired`, новые платежи отвергаются с `409 no_active_connection`, в журнал пишется `connection.session_expired`. Восстановление — повторный вход по SMS в кабинете. Поэтому номер кассира, отданный платформе, должен быть выделенным. ## Лимиты Частота запросов ограничена по ключу. Тарифные лимиты считаются по **оплаченным** платежам, а не по выставленным счетам: брошенные покупателем счета квоту не расходуют. ## Полный список эндпоинтов ``` POST /v2/qr создать QR POST /v2/invoices счёт на телефон GET /v2/operations список операций GET /v2/operations/{id} операция по id POST /v2/operations/{id}/cancel отменить POST /v2/refunds возврат POST /v2/subscriptions регулярный счёт GET /v2/subscriptions список регулярных счетов GET /v2/subscriptions/{id} регулярный счёт по id PATCH /v2/subscriptions/{id} изменить со следующего счёта POST /v2/subscriptions/{id}/pause пауза POST /v2/subscriptions/{id}/resume возобновить POST /v2/subscriptions/{id}/cancel отменить GET /v2/subscriptions/{id}/invoices счета регулярного счёта POST /v2/payment-links постоянная ссылка на оплату GET /v2/payment-links ссылки со статистикой GET /v2/payment-links/{id} ссылка по id PATCH /v2/payment-links/{id} изменить, выключить GET /v2/events журнал событий GET /v2/status health, без ключа POST /v2/sandbox/operations/{id}/pay песочница: оплатить POST /v2/sandbox/operations/{id}/expire песочница: просрочить POST /v2/sandbox/operations/{id}/reject песочница: клиент отклонил счёт POST /v2/sandbox/subscriptions/{id}/bill-now песочница: следующий шаг подписки сейчас POST /v2/sandbox/connections/{id}/kill-session песочница: убить сессию ``` Управление аккаунтом (`/me/*`, по токену кабинета): ключи, подключения Kaspi, вебхуки, уведомления, подписка, операции и события на чтение.