База знаний ApiPay — приём платежей Kaspi через API

Начало работы 13 статей

Первое подключение: кассир, номера, песочница, тарифы и вход в кабинет.

Анкета о бизнесе и лимит 1 платёж в деньМолодая организация до одобрения анкеты о бизнесе создаёт 1 реальный счёт в сутки. Зачем это, как заполнить анкету на /business-profile и снять лимит. Как выставлять счета Kaspi вручную из кабинета — без кода?Кабинет apipay.kz — это готовый инструмент: счета по номеру, возвраты, экспорт, команда. На нём можно выставлять десятки–сотни счетов в день вручную, без API. Можно ли подключить двух кассиров к одной организации ApiPay?Да: несколько кассиров на одну организацию ApiPay, каждый — отдельный номер. Когда нужен второй кассир, а когда менеджерский доступ или вторая организация. Как интегрировать ApiPay с помощью ИИ-агента?Дайте ИИ ссылку llms.txt или openapi.json — и он построит приём платежей Kaspi. Автономный sandbox-цикл из 3 шагов: счёт → simulate-status → проверка вебхука. Кассир Kaspi не подключается — почему и что делать?Kaspi просит пароль, видеоверификацию или ИИН, код из SMS не приходит? Разбор причин по частоте и что делать с каждой — от ролей номера до паузы Kaspi. Как настроить ApiPay за 15 минут — с ИИ или вручнуюНастройка ApiPay за ~15 минут: регистрация по WhatsApp, кассир за 2–3 минуты по SMS, интеграцию пишет ваш ИИ-ассистент. Запасной путь — вручную, без кода. Чем песочница отличается от рабочего режима в ApiPay?Песочница ApiPay бесплатна: счета не уходят в Kaspi, оплату имитируете сами. Как включить рабочий режим, почему удаляются тестовые ключи и что проверить. Как подключить свою Kaspi-кассу к ApiPay?Пошагово: мастер подключения кассира за 2–3 минуты, код из SMS живёт около минуты, 3 обязательных правила. После привязки — 3 дня бесплатного доступа. Перешёл в рабочий режим — не работает: что проверить?После перехода в прод счета не уходят, ключи «пропали», покупатель видит «Пожалуйста, повторите позднее»? Причины по частоте и решения за 5 минут. Кассир уволился или сменился номер — что делать в ApiPayЖитейские ситуации: кассир уволился, сменился его номер, поменялся владелец бизнеса, временно некому быть кассиром. Что нажать в кабинете и сколько это займёт. Сколько стоит ApiPay и берёт ли он комиссию с платежей?Тарифы ApiPay: Старт 10 000 ₸/мес (до 30 счетов/день), Бизнес 25 000 ₸ (до 100), Про 60 000 ₸ (100–300), 300+ — договорная. Фикс, 0% с оборота. Какой тестовый период у ApiPay и что в него входит?3 бесплатных дня рабочего режима — включаются автоматически при подключении кассира. Лимит теста — 50 счетов/день. Песочница бесплатна всегда, без кассира. Какой номер подходит для кассира Kaspi и почему ваш не прошёлТри условия для номера кассира: реальная SIM, на ИИН владельца нет ИП/ТОО в Kaspi Pay, только роль «Кассир». Чек-лист: почему Kaspi просит пароль или видео.

Решение проблем 13 статей

Что проверить, когда что-то не работает: оплата, кассир, вебхуки, возвраты, счета.

Как принимать Kaspi на сайте без Kaspi-магазина?Плейбук для интернет-магазинов на Tilda, WordPress и самописных сайтах: приём Kaspi через REST API поверх Kaspi Business — счёт по номеру и вебхук. Как связать свою CRM с Kaspi-оплатами?Минимальный контракт: создать счёт по номеру, принять вебхук paid, двигать карточку сделки. Идемпотентность против дублей, отдельные токены на каждую CRM. Как продавать через Telegram-бота с оплатой Kaspi?Плейбук для ботоводов: счёт по номеру, push в Kaspi, вебхук на выдачу товара. Деньги сразу на ваш счёт, мульти-бренд, защита от спама неоплаченных счетов. Как вендинговому автомату принимать оплату Kaspi без терминала?Покупатель вводит номер на автомате → счёт в Kaspi → оплата → вебхук → выдача товара. Рабочая схема для сетей вендинговых автоматов с собственным ПО. Как выставлять Kaspi-счета из 1С через API ApiPay?Рецепт для 1С: счёт из документа (POST /invoices и bulk), поллинг оплаты 1000/min под 1С, маппинг номенклатуры через external_ref, возвраты и sandbox-прогон. Как принять оплату Kaspi на сайте: виджет или свой код?Два рабочих пути: готовый widget.js (кнопка + QR, ≤10 КБ) или свой бэкенд со счётом по номеру и вебхуком. Полный код Node/Express, честно про Tilda. Как принимать оплату Kaspi в Telegram-боте?Рабочий рецепт: бот выставляет счёт через ApiPay, покупатель платит по push в Kaspi, вебхук подтверждает оплату в чат. Полный код на Python (aiogram) и Node. Лимиты и квоты ApiPay: полный справочникВсе лимиты ApiPay в одной таблице: 200 запросов/мин на ключ, счёт 24 ч, QR 5 мин, описание ≤500/≤100, возврат ~14 дней, вебхуки 11 ретраев. Пачка счетов Kaspi массово отменяется — почему?Счета пачкой уходят в cancelled при массовом выставлении? Это реакция на слишком плотный залп, не поломка. Решение — распределять во времени и bulk-выставление. Оплата Kaspi не приходит покупателю — что делать?Счета создаются, а оплата клиенту в Kaspi не приходит и денег нет? Чаще всего включён тестовый режим. Проверка: песочница, тариф, авторизация кассира. Привязка кассира разорвалась — как переподключить за минутуИногда привязка кассира разрывается и приём счетов встаёт. Переподключение — около минуты: Настройки → «Авторизация Kaspi». Как переподключить и не повторять. Не проходят оплаты: проблема у вас или у Kaspi?Диагностика за 2 минуты: три вопроса, чтобы понять, дело в вашей настройке, в сбое на стороне Kaspi или в плановых работах ApiPay. Фискальный чек Kaspi для наличных и чужого POS: как выбить через APIНаличные и POS другого банка не создают чек Kaspi автоматически. Как выбить фискальный чек в Kaspi OFD из кабинета или по API: превью, ссылка, идемпотентность.

Для вашего бизнеса 10 статей

Как приём Kaspi устроен под ваш сценарий: платформа, бот, сайт, точка, автопарк, школа.

Как SaaS-платформе принимать оплату Kaspi за клиентов?Плейбук для платформ и агрегаторов: каждый клиент получает деньги на свой Kaspi-счёт, платформа хранит API-ключи и выставляет счета от их имени. Как настроить полностью автоматический приём Kaspi для клиентов?Партнёр автоматизирует всё через Partner API: клиент лишь диктует код из Kaspi-SMS. Онбординг, счета, тариф-счёт и вебхуки — без захода в кабинет ApiPay. Безопасно ли подключать ApiPay и как он устроен?ApiPay — независимый сервис поверх вашего Kaspi Pay: роль «Кассир» без доступа к деньгам, оплата идёт напрямую на ваш Kaspi-счёт. Права, звонки СБ, отключение. Можно ли несколько организаций на один аккаунт ApiPay?Да: один аккаунт — несколько организаций, у каждой свой кассир, API-ключ и отдельный тариф (тарифы не суммируются). Для платформ — Partner API и white-label. Не могу войти в ApiPay: код не приходит или нет профиля?Не пускает в кабинет apipay.kz? Чаще всего вход идёт не с того номера: личный номер регистрации — не номер кассира. Разбор причин и что писать в поддержку. Как встроить приём Kaspi в свой продукт через Partner API?Один ключ X-Partner-Key держит N организаций мерчантов, у каждой свой X-API-Key и вебхук. 2 ключа, 2 границы, HMAC по raw body, тариф-биллинг — на партнёре. Как партнёру подключить организацию мерчанта к ApiPay?Partner API за 7 шагов: создать организацию, авторизовать кассира по SMS, выдать per-org X-API-Key, выставить первый счёт. Сначала sandbox, потом прод. Словарь ApiPay: термины простыми словамиЧто такое кассир, номер кассира, сессия, API-ключ, вебхук, песочница, счёт по номеру и QR-счёт — 20 терминов ApiPay простыми словами, с аналогиями и ссылками. Что где находится в кабинете ApiPayЭкскурсия по кабинету ApiPay: Счета с экспортом и фильтрами, Настройки с ключами и логом уведомлений, Мой тариф, переключатель организаций, встроенные гид-туры. Как войти в кабинет ApiPay, если нет логина и пароля?Вход на apipay.kz — по личному номеру через WhatsApp: кнопка «Подтвердить» или код на 5 минут. Чек-лист «код не пришёл», лимиты запросов и доступ для команды.

Справочник 24 статьи

Технические детали для разработчиков: счета, вебхуки, возвраты, подписки, лимиты, термины.

API-ключ и вебхук-секрет ApiPay: в чём разница?API-ключ (X-API-Key) авторизует ваши запросы; вебхук-секрет только проверяет подпись входящих вебхуков. Где взять, когда перегенерируются, почему «пропадают». Как автошколе или онлайн-школе принимать оплату Kaspi?Плейбук для автошкол, курсов и абонементов: счета из кабинета без кода, подписки как авто-выставление (не автосписание), ссылки на оплату в WhatsApp. Как принимать Kaspi QR на офлайн-точке через ApiPay?Кассир показывает динамический QR на экране — покупатель сканирует и платит. QR живёт 5 минут, как на терминале. Когда QR, а когда счёт по номеру на 24 часа. Как таксопарку выставлять сотни счетов Kaspi водителям?Плейбук массового биллинга: счета водителям по спискам, идемпотентность против дублей и bulk-выставление — как надёжно проводить сотни счетов в день пачками. Чек-лист безопасности интеграции ApiPay: 12 пунктов12 проверок безопасности интеграции ApiPay: API-ключ только на сервере, подпись вебхука по raw body, что делать при утечке ключа, ротация секретов. Что видит покупатель при оплате счёта через ApiPay?Путь покупателя: счёт приходит в его приложение Kaspi, оплата в пару касаний со своего Kaspi Gold/Red. Счёт живёт 24 часа, QR — около 5 минут. Никаких ссылок. Как создать счёт Kaspi по номеру телефона через API?Один POST-запрос — и покупатель получает push в Kaspi. Счёт живёт 24 часа, оплата видна за 10–20 секунд. Статусы, идемпотентность, «странные» переходы. Как выбить фискальный чек Kaspi из кабинета ApiPayПошагово для продавца: как выбить фискальный чек Kaspi OFD из кабинета ApiPay при оплате наличными или через POS другого банка. Без кода, простыми словами. Каталог для 1С в ApiPay: синхронизация без дублейПлейбук синка каталога из 1С в ApiPay: external_ref как ключ маппинга, match-and-merge и идемпотентность, подтверждение вебхуком или поллингом, лимиты и ошибки. Каталог, корзина и Нацкаталог (ntin/gtin) в ApiPayТовары через POST /catalog (батч 1–100), продажа корзиной cart_items, скан штрихкода в Нацкаталоге (ntin/gtin), чтение каталога в 4 режимах для синхронизации. Массовая заливка каталога 1С в ApiPay: очередь, ETA, ошибкиПлейбук массовой заливки каталога из 1С: батчи по 100 с Idempotency-Key, поллинг очереди с ETA, вебхук catalog.batch_processed и разбор ошибок заливки. Как настроить вебхуки ApiPay и проверить подпись?Настройка за 5 минут: URL + секрет + проверка HMAC по raw body (X-Webhook-Signature). Ретраи 11 раз, circuit breaker, почему поллинг — плохая идея. Ошибка 422 cart_items — как исправить счёт с корзиной?422 requires cart items, затем has no price set? Это Каспи ОФД: счета только с корзиной. Цепочка исправлений по шагам — от каталога до скидок и RFO-кода. Подписки ApiPay: есть ли автосписание с покупателя?Нет: подписка ApiPay — авто-выставление счёта Kaspi по расписанию, оплату покупатель подтверждает сам. Ретраи, grace-период 3 дня, события subscription.*. QR Kaspi показывает «Попробуйте позже» — что делать?Покупатель сканирует QR и видит «Попробуйте позже»? Чаще всего QR истёк: он живёт ~5 минут. Разбор причин: TTL, песочница, описание длиннее 100 символов. Почему QR-счёт Kaspi живёт 5 минут и что это меняет?QR-счёт ApiPay действует ~5 минут — как QR на кассе, это не баг. Описание до 100 символов, QR-счета сосуществуют. Когда выбирать QR, а когда счёт на 24 часа. Как разделить счета по точкам в одной организации ApiPay?Отдельный API-ключ на каждую точку: счета пометятся именем ключа (колонка «Источник»), у точки свои вебхуки. Деньги, тариф и лимиты — общие на организацию. Счета дублируются или создаются сами — как остановить?Покупатель получил два счёта, CRM льёт счета потоком? Экстренная остановка: удалите API-ключи — интеграция отключится мгновенно. Затем идемпотентность. Счета с корзиной (cart_items): как исправить ошибку 422?422 про cart_items значит: организация работает с каталогом (Kaspi ОФД). Схема корзины, цена позиции, переопределение цены, скидка и чек-лист исправления. Возврат Kaspi не проходит — в чём причина?«Возврат создан», а деньги не вернулись? Чаще всего на Kaspi-счёте не хватает суммы из-за комиссии Kaspi. Разбор причин по частоте и кросс-чек за минуту. Как сделать возврат Kaspi через API и почему он не проходит?Возврат: POST /invoices/{id}/refund или кнопка в кабинете. Окно ~14 дней, до 3 попыток, частичный по сумме или штукам. Частая причина отказа — нехватка средств. Вебхук ApiPay не приходит — как найти причину?Вебхук молчит: перегенерировался ключ после привязки организации, URL недоступен, подпись не сходится или сработал circuit breaker. Диагностика по шагам. Как заполнить каталог товаров в ApiPay: поля, штрихкод, НТИНИнструкция по каталогу ApiPay: какие поля заполнять и на что влияют, правило «один штрихкод = один товар», когда НТИН попадает в чек Kaspi и как дорезолвить. Жизненный цикл счёта: от создания до денегСчёт ApiPay: created → processing → pending → paid/cancelled/expired. Тайминги, легитимный cancelled→paid, когда приходят деньги и какой вебхук на шаге.