Как подключить Kaspi Pay к сайту: схемы, этапы и частые ошибки

Чтобы подключить Kaspi Pay к сайту, нужно пройти три этапа: оформить отношения с банком как продавец, выбрать схему приёма оплаты (ссылка или счёт, QR, интеграция через программный интерфейс) и реализовать на сайте связку заказа с платежом, включая подтверждение оплаты. Какая именно схема вам доступна и на каких условиях, определяется договором и текущей документацией банка, поэтому всё, что касается точных параметров, нужно сверять у менеджера и в личном кабинете. Ниже я описываю логику, которая помогает не ошибиться в архитектуре, не привязываясь к деталям, которые меняются.

Какие схемы приёма оплаты существуют вообще

Когда говорят «подключить Kaspi Pay к сайту», подразумевают разные вещи. Прежде чем писать код, стоит определить, о какой схеме идёт речь.

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

Вторая: оплата по QR-коду. Покупатель сканирует код в приложении. Удобно для офлайн-точек и для мобильных сценариев, на сайте обычно показывают код и ждут подтверждения.

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

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

Этап первый: договор и доступы

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

Что стоит подготовить заранее:

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

Банки обычно проверяют сайт перед запуском, и страница без условий возврата или контактов становится причиной задержки. Составлять оферту и политику возврата лучше с юристом, я здесь только напоминаю, что они должны существовать.

После заключения договора вы получите доступы в личный кабинет и, при интеграции через API, идентификаторы и ключи для запросов. Эти данные нужно хранить как секреты: не в репозитории, не в клиентском коде, а в переменных окружения или в закрытом конфигурационном файле на сервере.

Этап второй: как должна выглядеть логика на стороне сайта

Независимо от схемы, правильная архитектура состоит из одних и тех же элементов. Я описываю её как последовательность.

1. Покупатель оформляет заказ. Сайт сохраняет его в статусе «ожидает оплаты» и присваивает внутренний идентификатор.
2. Сайт создаёт платёж у провайдера или формирует счёт, передавая сумму и ваш идентификатор заказа. Идентификатор нужен, чтобы потом связать ответ с заказом.
3. Покупатель переходит к оплате в приложении или на странице провайдера.
4. Провайдер сообщает об итоге: уведомлением на ваш адрес, ответом на запрос статуса или обоими способами.
5. Сайт проверяет подлинность сообщения, сверяет сумму и идентификатор, меняет статус заказа и запускает дальнейшие действия (отправка, выдача, уведомление клиента).

Ключевое правило: статус «оплачен» ставится только на основании подтверждения от провайдера, а не потому, что покупатель вернулся на страницу «Спасибо». Возврат на страницу можно подделать вручную, закрыть вкладку до него или потерять по сетевой причине.

Подтверждение оплаты: уведомление против опроса

Здесь чаще всего возникают проблемы. Есть два способа узнать результат: ждать уведомления от провайдера или самому периодически спрашивать статус. Надёжнее сочетать оба.

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

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

Безопасность: что проверять в каждом запросе

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

Какие механизмы подлинности использует провайдер (подпись, секретный ключ, список разрешённых адресов, проверка статуса обратным запросом), определяет его документация. Моя общая рекомендация: никогда не доверяйте полям запроса без проверки. Даже если подпись валидна, сверьте сумму и валюту с тем, что хранится в вашем заказе. Сумму в запросе на создание платежа формируйте на сервере по данным заказа, а не принимайте с клиента.

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

Секреты не должны попадать в логи, ответы пользователю и клиентский код. Журнал полезен, пока в нём не лежат ключи.

Тестовая среда и запуск

Если банк предоставляет тестовую среду или тестовый режим, пользуйтесь им до конца. Если нет, договоритесь, как проверить интеграцию с минимальными реальными суммами, и заранее продумайте возврат этих платежей.

Сценарии, которые нужно проверить до запуска:

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

Подробный чек-лист по проверке интеграций я собрал в статье про тестирование платёжной интеграции.

Частые ошибки при подключении

Статус по возврату покупателя на сайт. Самая распространённая ошибка, из-за которой при нестабильной связи часть оплаченных заказов остаётся без статуса, а часть неоплаченных можно открыть вручную.

Отсутствие собственного идентификатора платежа. Без него при сбое тяжело сопоставить операцию банка с заказом, а позже и сверить поступления в учёте.

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

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

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

Жёстко прописанные адреса и ключи в коде. При переезде с тестовой среды на рабочую приходится править код, а это источник ошибок. Выносите настройки в конфигурацию.

Нет связи с учётом. Оплаты видны в кабинете банка, но не в 1С, и бухгалтер сверяет всё вручную. Заранее продумайте, как платёж попадёт в учёт, например по схеме из статьи про автоматическую сверку платежей с 1С.

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

Сколько времени занимает подключение?

Зависит от скорости согласования с банком и от выбранной схемы. Техническая часть при простой схеме может быть небольшой, а договорная и проверка сайта часто занимают больше времени. Сроки лучше уточнять у менеджера банка.

Можно ли принимать оплату без интеграции через API?

Во многих случаях да: ссылка или счёт, QR-код, ручное подтверждение. Это нормально для небольших объёмов. С ростом заказов ручное подтверждение становится узким местом, и тогда нужна автоматизация.

Нужен ли отдельный разработчик на стороне сайта?

Если у вас готовый конструктор или CMS, возможно, есть готовый модуль. Проверьте, поддерживает ли он нужную вам схему и актуальную версию интерфейса банка. Для самописного сайта интеграцию делает разработчик, знакомый с платёжными сценариями.

Что делать, если оплата прошла, а заказ не обновился?

Найдите платёж по идентификатору в кабинете банка, запросите его статус и приведите заказ в соответствие. Затем разберитесь, почему не сработало уведомление, и добавьте задачу автоматической проверки, чтобы такие случаи закрывались без вашего участия.

Если вы планируете принимать оплату на сайте и хотите обсудить схему, посмотрите раздел об интеграциях платёжных систем или напишите в Telegram.