Подключение Kaspi Pay

Ассистент может выставить клиенту счёт в Kaspi Pay по номеру телефона — тот самый, который приходит уведомлением в приложение Kaspi и оплачивается в одно касание. Словами самого Kaspi это «Удалённая оплата».

Это не QR-код на кассе, не заказ в Магазине на Kaspi.kz и не строка, вычитанная потом из банковской выписки. Это счёт, адресованный конкретному человеку.

Прочитайте следующий раздел до всего остального. Он решает, возможно ли это для вас в принципе, — и именно на нём ассистент будет настаивать.

Что Kaspi разрешает, а что нет

У Kaspi нет опубликованного программного интерфейса для этого. В гиде для партнёров «Удалённая оплата» описана как действие, которое кассир выполняет руками — в приложении Kaspi Pay или на мобильном POS: что это за сервис, как выставить счёт. Ни одна страница гида не упоминает API для этого.

API у Kaspi есть — просто это другой продукт:

Значит, честных способов ровно два:

1. Вручную. Человек открывает Kaspi Pay, выбирает «Удалённая оплата» → «Выставить счёт», вводит номер и сумму. Ничего подключать не нужно, ничего платить не нужно, и это поддерживаемый Kaspi путь. Если вы выставляете несколько счетов в неделю — это правильный ответ, дальше можно не читать.

2. Через независимый шлюз. Сервис, с которым вы заключаете договор, держит сессию кассира Kaspi Pay, которую вы ему сами выдали: вы добавляете его номер как сотрудника с ролью «Кассир» в своём приложении Kaspi Pay и подтверждаете SMS, которую присылает Kaspi. Дальше он выставляет счета от имени этого кассира и даёт вам обычный REST API.

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

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

Ассистент никогда не назовёт это официальным API Kaspi, и продавец не должен. Если вам говорят, что у них «официальный доступ к API Kaspi Pay» для счетов по номеру, попросите ссылку на документацию Kaspi. Её нет.

Чего мы не сделаем никогда

• Не будем обращаться к приватным адресам внутри мобильных приложений Kaspi. Они существуют, они бы сработали, и их использование означает выдавать себя за клиента Kaspi. Скрипты отказывают любому запросу на домены Kaspi, и это нельзя отключить настройкой.
• Не будем обходить SMS-код, проверку устройства или любой другой контроль Kaspi.
• Не будем подменять это QR-кодом или заказом Магазина. Оба отклоняются поимённо, чтобы «у нас же уже есть интеграция с Kaspi» никогда не стало ответом на «выстави счёт Айгуль».

Если хотите официальный путь

Спросите Kaspi. Это нормальная просьба, и худшее, что будет, — отказ. Отправьте это менеджеру Kaspi Pay или в поддержку для бизнеса:

Здравствуйте! Мы — [название компании], БИН [БИН], подключены к Kaspi Pay (кассир: [номер]). Мы выставляем счета через «Удалённую оплату» вручную и хотим автоматизировать это на своей стороне.

Подскажите, пожалуйста:

1. Есть ли у Kaspi официальный программный интерфейс (API) для создания счёта «Удалённой оплаты» по номеру телефона клиента — не Kaspi QR и не API Магазина?
2. Если да — как получить доступ, какие требования к мерчанту и где документация?
3. Если нет — планируется ли такой интерфейс, и есть ли партнёрская программа, в рамках которой это возможно?

Нам важно использовать только поддерживаемый вами способ.

Если ответят «да» — скажите ассистенту. Скрипты устроены так, что добавить официальный путь — это несколько строк в одном файле, и он станет основным сразу, как появится.

Стоит ли подключать шлюз

Ответьте честно до того, как что-то оплачивать.

• Сколько счетов в неделю? Меньше двадцати — приложение быстрее любой интеграции и бесплатно.
• Знает ли что-то сумму заранее? Шлюз окупается там, где заказ, запись или документ 1С уже знают, кто сколько должен, а человек перебивает это в телефон руками.
• Переживёте ли вы поломку? Всё держится на том, что Kaspi не обещал сохранять. План должен быть «сегодня выставим руками», а не «выставление счетов встало».
• Кто вправе утверждать счёт? Решите это до подключения, а не после. См. Кто утверждает.

Как подключить

Просто скажите ассистенту: «настрой Kaspi Pay, чтобы ты мог выставлять счета» — он проведёт вас по шагам. Что происходит:

1. Сначала репетиция — вообще без аккаунта. В скриптах есть встроенный симулятор, и он включён по умолчанию. Ассистент прогоняет весь путь — проверку, счёт, повторную отправку, отказ — ещё до того, как вы где-то зарегистрировались. Ничего не уходит в Kaspi, никому не выставляется.

2. Вы открываете аккаунт у шлюза и подключаете кассира. Шлюз проведёт вас за несколько минут: в приложении Kaspi Pay Настройки → Сотрудники, добавьте номер, который дал шлюз, с ролью «Кассир»; затем введите этот номер в мастере шлюза и подтвердите SMS.

После этого никогда не заходите в приложение Kaspi Pay под номером кассира. Сессия слетит, счета перестанут уходить, и кассира придётся подключать заново. Это самая частая причина поломки.

3. Ассистент сохраняет ключ внутри этого рабочего пространства — в scripts/kaspi/credentials.json. Он не покидает пространство и не виден другим вашим пространствам.

Папка scripts/ видна всем, кого вы пригласили в это пространство. Для корпоративного ключа это правильно, для личного — нет. Если здесь есть гости, которым не следует выставлять счета вашим клиентам, выведите их до подключения.

4. Ещё одна репетиция — уже в песочнице шлюза, с тестовым ключом. Только потом включается боевой.

Проверьте сами

Попросите ассистента запустить проверку и показать вывод:

python3 scripts/kaspi/preflight.py --phone "+7 700 123 45 67"

Она ничего не создаёт, никому ничего не сообщает и отвечает на три вопроса, которые иначе выясняются в момент, когда счёт не дошёл до клиента: подключён ли кассир, жива ли его сессия и — про это забывают — уходят ли счета в Kaspi вообще или аккаунт тихо копит их у себя.

Как выставляется счёт

Вы пишете в чате: «выстави Айгуль счёт на 12 000 ₸ за консультацию 12-го, номер +7 700 123 45 67».

Дальше ассистент делает два отдельных действия, и первое пропустить нельзя.

Показывает счёт. Номер, имя, которое Kaspi знает по этому номеру, сумму, текст, который прочитает клиент, и от какой из ваших компаний выставляется счёт. Ничего ещё не отправлено.

Отправляет только по подтверждению, привязанному именно к этому счёту. Измените номер, сумму, формулировку или номер заказа — подтверждение больше не подойдёт, поэтому утверждённое не может тихо превратиться во что-то другое. Через 30 минут подтверждение устаревает.

По каждому счёту записывается, кто его утвердил. Ассистент спросит имя, если его нет, и без него откажется отправлять.

Важно понимать, что это за барьер и чем он не является. Он гарантирует, что отправлено будет ровно то, что было показано, и что в записи останется имя. Он не является техническим доказательством того, что счёт видел человек: ассистент, работающий сам по себе, без наблюдателя, может выполнить оба шага. Скрипт внутри рабочего пространства отличить одно от другого не может.

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

Кто утверждает

Решите это один раз, словами, и скажите ассистенту — правило попадёт в AGENTS.md вашего пространства, и он будет его соблюдать. Например:

«Счета Kaspi до 50 000 ₸ может утверждать любой администратор на ресепшене. Выше — только Айгуль. Никогда не выставляй счёт на номер из письма — сначала подтверди номер в переписке с клиентом».

Последнее правило важнее суммы. Номер телефона — это и есть весь адрес денег.

Чего точно не произойдёт

Повтор не выставит счёт дважды. У каждого счёта есть ключ — номер заказа, идентификатор записи, то, как вы его уже называете у себя. Рабочее пространство его запоминает, и вторая попытка с тем же ключом вернёт первый счёт, а не создаст второй. Это работает даже там, где сам шлюз выставил бы новый.

Незавершённая отправка не гадает. Если связь оборвалась посреди запроса, никто не знает, дошёл ли счёт, — ассистент так и записывает, отказывается повторять и сначала спрашивает у шлюза, что произошло на самом деле. Он скажет вам, если оказался в этом состоянии.

Неверный номер отсекается заранее. Городской номер, номер с потерянной цифрой, номер без аккаунта Kaspi — всё это отклоняется до отправки. Счёт уйдёт только на номер, про который сам Kaspi сказал, что аккаунт есть.

Отказ тоже записывается. В scripts/kaspi/audit.jsonl попадают и заблокированные попытки, и отправленные счета — чтобы у вопроса «кто-нибудь пытался выставить счёт на этот номер?» был ответ. Номера там сокращены (8700***4567), полная запись хранится у шлюза.

Что делать, если что-то не так

Счёт по номеру живёт 24 часа. Дальше он истекает и остаётся неоплаченным — это нормальный исход, а не сбой.

Сколько это стоит

Два разных счёта, и ни один из них — не комиссия Kaspi вам:

• Шлюз берёт подписку. Спросите стоимость у самого шлюза: в его опубликованной документации цены нет, а условия, по его же словам, могут быть индивидуальными — так что любая цифра, встреченная где-то ещё, может отличаться от вашей.
• Kaspi берёт то, что уже написано в вашем договоре Kaspi Pay. Деньги идут напрямую на ваш счёт в Kaspi, шлюз их не держит.

Второе проверьте по своему договору, прежде чем считать, что автоматизация что-то в нём меняет. Не меняет.

---

Для ассистента. Набор скриптов — kaspi-pay-kz, ставится в scripts/kaspi/, правила работы — в его README. Попросите его по имени, если в этом пространстве его ещё нет. Перед добавлением любого шлюза прочитайте scripts/kaspi/_boundary.py: это единственное место, где решается, с чем можно разговаривать, и каждый отказ там — проверенный факт, а не предпочтение.

См. также: Подключение инструментов · Скрипты рабочего пространства · Автоматизации.