Что Kaspi Pay даёт интернет-магазину и чего в нём нет
Kaspi Pay для бизнеса собран вокруг двух групп сценариев. В точке продаж работают мобильный POS, Smart POS и статичный QR. Для дистанционной оплаты Kaspi предлагает счёт для оплаты и оплату по ссылке: продавец формирует счёт или ссылку, покупатель открывает её в приложении Kaspi.kz и подтверждает списание. Ссылку можно отправить в мессенджер, опубликовать в соцсети или разместить на сайте. Счёт Kaspi Pay открывается онлайн, за подключение к сервису берётся ежемесячная абонентская плата, актуальный размер которой имеет смысл смотреть прямо в кабинете, а не в статьях годичной давности.
Отсюда следует вывод, который владельцу магазина лучше сделать до начала работ. Интеграция Kaspi Pay на сайте 1С-Битрикс редко означает то же самое, что подключение классического интернет-эквайринга с формой ввода карты на странице оплаты. Механика другая: деньги списываются внутри приложения покупателя, а задача сайта сводится к тому, чтобы корректно эту оплату инициировать и потом узнать её результат.
Разница кажется косметической ровно до того момента, когда магазин начинает считать заказы. При эквайринге статус «оплачен» приходит на сайт сам. При оплате по ссылке или счёту без дополнительной работы на сайте про факт оплаты не знает никто: менеджер видит поступление в приложении Kaspi Pay и меняет статус заказа руками. На пяти заказах в день это терпимо. На пятидесяти начинается расхождение между тем, что показывает сайт, и тем, что реально оплачено.
Три сценария приёма оплаты Kaspi на сайте 1С-Битрикс
Практически все проекты, которые к нам приходят с задачей «подключите Kaspi к сайту», укладываются в один из трёх вариантов. Они отличаются не столько технологией, сколько тем, сколько ручной работы остаётся у менеджера.
Ручной сценарий. Покупатель оформляет заказ на сайте, выбирает способ оплаты «Kaspi», получает уведомление, что с ним свяжутся. Менеджер формирует счёт или ссылку в приложении Kaspi Pay и отправляет её покупателю в WhatsApp. Со стороны 1С-Битрикс тут нужен минимум: новый способ оплаты без автоматики, инструкция для клиента и текст письма. Это законный вариант для магазина с десятком заказов в неделю, и его недооценивают: он запускается за день и не требует никаких договорённостей, кроме уже открытого счёта Kaspi Pay.
Полуавтоматический сценарий. Ссылка на оплату генерируется заранее и подставляется в карточку заказа, письмо и страницу «спасибо за заказ». Покупатель платит сразу, не дожидаясь менеджера. Обратной связи от Kaspi сайт по-прежнему не получает, поэтому статус заказа кто-то закрывает вручную или по выгрузке из банка. Конверсия при этом заметно выше, чем в первом варианте, потому что оплата происходит на пике желания купить, а не через сорок минут.
Полная интеграция. Сайт умеет и создать платёж, и получить подтверждение, и провести возврат. Это то, что обычно имеют в виду под словами «онлайн платежи 1с битрикс» применительно к Kaspi. Такой сценарий требует отдельных договорённостей с Kaspi, доступа к техническим материалам и разработки на стороне сайта. Ниже разберу его подробнее, потому что именно на нём проекты чаще всего спотыкаются.
Как 1С-Битрикс принимает платежи изнутри
Модуль интернет-магазина в 1С-Битрикс работает с платежами через обработчики платёжных систем. Обработчик отвечает за то, что происходит, когда покупатель нажимает кнопку оплаты: какую форму ему показать, какие параметры заказа отправить наружу, как принять ответ и что после этого сделать с платежом.
Система ищет обработчики в нескольких каталогах. Пользовательский путь задаётся опцией path2user_ps_files и по умолчанию указывает на /php_interface/include/sale_payment/. Есть локальный путь /local/php_interface/include/sale_payment/. Системные обработчики лежат в /bitrix/modules/sale/handlers/paysystem/, а старые в /bitrix/modules/sale/payment/. Если ваш обработчик называется так же, как системный, он системный подменяет, и оригинал в списке доступных вариантов больше не появляется.
Минимальный обработчик состоит из двух файлов. В handler.php лежит класс, который наследуется от ServiceHandler или от BaseServiceHandler. Первый вариант для автоматизированных платежей, второй для неавтоматизированных, вроде квитанции. В .description.php описываются настройки: массив $data с параметрами конфигурации и переменная $description. Именно из этого файла берутся поля, которые администратор потом заполняет в админке, когда заводит платёжную систему.
Класс обязан находиться в пространстве имён \Sale\Handlers\PaySystem\, иначе он просто не подключится. Есть ещё два ограничения на имя папки, о которые спотыкаются даже опытные разработчики: имя должно быть в нижнем регистре и не должно содержать слово handler. Возврат и удержание средств реализуются через интерфейсы IReturn и IHold.
Всё это относится не только к Kaspi. Ровно так же на 1С-Битрикс подключается любая платёжная система, для которой нет готового решения, и по той же схеме мы делаем разработку сайтов под ключ для казахстанских магазинов, где к типовому набору оплат почти всегда добавляется что-то местное.
Почему готового модуля из маркетплейса, скорее всего, не будет
Первое, что делает разработчик, получив задачу: идёт в маркетплейс 1С-Битрикс и ищет решение по слову Kaspi. Результат стоит знать заранее. По этому запросу маркетплейс отдаёт один модуль, и это модуль обмена товарами и заказами с маркетплейсами от ACRIT, где Kaspi стоит в одном ряду с Ozon, Wildberries, AliExpress и Сбер МегаМаркетом. Он про выгрузку каталога и приём заказов с торговой площадки Kaspi, а не про приём оплаты на вашем собственном сайте.
Это принципиально разные задачи. Магазин на площадке Kaspi живёт по правилам площадки, там оплата уже встроена. Ваш сайт на 1С-Битрикс к этой инфраструктуре отношения не имеет, и модуль, который синхронизирует товары с площадкой, платёжной системой на сайте не становится.
Второй источник разочарования: публичной документации по мерчант-интеграции у Kaspi в открытом доступе нет. На сайте платёжной системы выложен технический регламент, но он описывает подключение участника платёжной системы, то есть стороннего мобильного приложения, которое умеет сканировать QR Kaspi и списывать деньги у своего клиента. Продавцу интернет-магазина этот документ показывает логику работы системы, но не даёт готовой инструкции для сайта. Технические материалы для мерчанта Kaspi выдаёт в рамках договора, поэтому первый шаг интеграции лежит не в коде, а в переписке с банком.
Что видно из технического регламента платёжной системы
Регламент полезно прочитать даже тем, кто не собирается становиться участником системы: он показывает, в каких терминах Kaspi думает про платёж, и помогает задавать банку правильные вопросы.
API работает по HTTP, все запросы отправляются методом POST, данные передаются в JSON по стандарту RFC 8259 с требованием игнорировать неизвестные поля при разборе ответа. Версия указывается прямо в URL, текущая первая: адрес выглядит как https://{host}/api/v1/qr/scan. Даты передаются в формате ISO 8601, суммы с двумя знаками после точки.
В заголовках запроса обязательны Content-Type: application/json, уникальный идентификатор запроса X-Request-ID длиной до 64 символов, присвоенный системой идентификатор участника X-Caller-Name длиной до 12 символов и язык X-Locale в значении ru-RU или kk-KZ. Любой ответ содержит объект result с полями resultCode и resultMessage. Значение SUCCESS в коде означает успех, всё остальное считается ошибкой, а текст ошибки лежит во втором поле.
Отдельно регламент требует идемпотентности. Повторно отправленный запрос с теми же аргументами не должен списывать деньги дважды. Это правило стоит перенести в собственный код на сайте независимо от того, по какой схеме вы интегрируетесь: сеть рвётся, менеджер жмёт кнопку второй раз, cron перезапускает задачу, и без защиты от дублей магазин рано или поздно проведёт один платёж как два.
Сам платёж в регламенте разложен на методы scan, checkout, notifyPayment и refund. Покупатель сканирует QR, приложение получает токен и отправляет его в scan, система отвечает типом токена и данными точки. Токены бывают динамические, статические и с дополнительными полями, а на возврат генерируется отдельный возвратный QR. Метод checkout возвращает сумму к оплате, notifyPayment подтверждает списание и отдаёт ссылки на товарный чек, в том числе в формате PDF. Возврат живёт отдельным методом, и его реализация обязательна для участника системы.
Как собирается обработчик Kaspi на стороне сайта
Когда договор подписан и технические материалы получены, работа на стороне 1С-Битрикс укладывается в понятный список.
Заводится папка обработчика в пользовательском или локальном каталоге, с учётом ограничений на имя. В .description.php описываются настройки, которые администратор будет заполнять: идентификатор точки, ключи доступа, адрес API, режим работы. Ключи хранятся в настройках платёжной системы, а не в коде, иначе первое же обновление сайта из репозитория утащит их в историю коммитов.
В handler.php реализуется создание платежа: обработчик собирает сумму и идентификатор заказа, обращается к API и получает то, что нужно показать покупателю. Дальше пишется приём подтверждения. Здесь важно не доверять входящему запросу на слово: проверяется подпись или иной механизм, который даёт банк, сверяется сумма из уведомления с суммой заказа в базе, проверяется, что заказ ещё не оплачен. Только после этого платёж помечается оплаченным средствами модуля продаж, а не прямым обновлением полей в таблице.
Возврат подключается через IReturn, чтобы менеджер делал возврат из карточки заказа, а не из двух систем сразу. И отдельно закладывается журнал: что именно ушло в банк, что пришло обратно, в какой момент. Через полгода, когда придётся разбирать спорный платёж, этот журнал окажется единственным способом восстановить картину.
Тестирование заслуживает отдельного пункта. Проверять нужно не только успешную оплату, но и брошенный платёж, оплату после истечения срока жизни ссылки, повторное уведомление по одному заказу и частичный возврат. Магазины ломаются именно на этих ветках, потому что счастливый путь разработчик проверяет всегда, а остальные обычно нет.
Ещё один пункт, который любят пропускать: поведение сайта при недоступности банка. Если API не отвечает, покупатель не должен видеть белый экран или ошибку PHP. Заказ создаётся, покупателю показывается понятное сообщение и альтернативный способ оплаты, а менеджер получает уведомление. Такая мелочь спасает несколько заказов в месяц, а стоит она полдня работы.
Рассрочка: почему её обсуждают отдельно
Разговор про Kaspi у казахстанского магазина почти никогда не заканчивается на обычной оплате. Kaspi Pay даёт продавцу продажи через Kaspi Red+ и Kaspi Kredit, и для части товарных категорий именно рассрочка определяет, купят у вас или нет. Сам Kaspi называет участие в акциях по рассрочке способом заметно увеличить продажи, и по нашему опыту в мебели, электронике и оборудовании это ощущается сильнее всего.
С точки зрения сайта на 1С-Битрикс рассрочка живёт по своим правилам, и складывать её в тот же обработчик, что и обычную оплату, обычно неправильно. Условия участия, доступные товарные категории и порядок расчётов с продавцом определяет Kaspi, а не разработчик, и уточнять их нужно в банке до того, как на карточке товара появится кнопка с обещанием рассрочки. Ошибка, которую мы видели не раз: магазин рисует на сайте красивый калькулятор ежемесячного платежа, не имея договорённости на эти условия, а потом объясняется с покупателями, почему на кассе получилось иначе.
Технически на стороне сайта задача обычно сводится к тому, чтобы корректно передать состав корзины и сумму, а также развести способы оплаты в оформлении заказа: обычная оплата и рассрочка становятся разными платёжными системами со своими настройками и своими статусами. Это удобнее и для учёта, потому что деньги по ним приходят по-разному.
Иллюстративный пример: магазин автозапчастей
Пример ниже собирательный, он нужен, чтобы показать порядок действий, а не как описание конкретного проекта.
Магазин автозапчастей в Алматы работает на 1С-Битрикс, около сорока заказов в день, оплата принимается двумя менеджерами вручную через приложение Kaspi Pay. Проблем две. Клиенты уходят, пока ждут ссылку, а в конце месяца бухгалтерия сводит поступления с заказами по выгрузке, и каждый раз находится десяток расхождений.
Первым шагом магазин не пишет код, а меняет процесс: ссылка на оплату теперь генерируется в момент оформления заказа и попадает и на страницу подтверждения, и в письмо, и в WhatsApp. Разработка занимает несколько дней. Доля оплаченных в первый час заказов растёт, потому что покупателю больше не нужно ждать менеджера.
Вторым шагом магазин идёт в Kaspi за договором на полноценную интеграцию, получает технические материалы и заказывает обработчик платёжной системы. После этого статус заказа закрывается автоматически, а сверка в конце месяца превращается в отчёт вместо расследования.
Порядок шагов здесь важнее самих шагов. Магазин сначала получил дешёвый прирост выручки, а потом потратил бюджет на автоматизацию, уже понимая, сколько она сэкономит. Обратный порядок встречается чаще и обходится дороже.
Что проверить до старта работ
Перед тем как обсуждать сроки и смету, полезно пройти короткий список.
Счёт Kaspi Pay открыт, доступ в кабинет есть у того человека, который будет участвовать в проекте. Понятно, какой сценарий из трёх вы выбираете и почему. Если выбран третий, запрос в Kaspi на технические материалы отправлен до того, как разработчик начал писать код: этот пункт чаще всего и определяет реальный срок запуска.
Дальше сайт. Версия 1С-Битрикс и лицензия модуля интернет-магазина актуальны, обновления накатываются. Есть тестовая копия сайта, на которой можно проверять оплату, не трогая живые заказы. Список статусов заказа приведён в порядок: если в системе три статуса на все случаи жизни, автоматизация оплаты сделает учёт только запутаннее.
Отдельно стоит посмотреть на карточку товара и оформление заказа глазами покупателя с телефона. Большая часть оплат Kaspi приходит со смартфона, и если кнопка оплаты уезжает под футер или ссылка открывается в новой вкладке без возврата на сайт, никакая аккуратная серверная часть этого не компенсирует.
И организационная часть. Кто отвечает за возвраты, кто смотрит журнал ошибок, что делает менеджер, если оплата прошла, а заказ остался неоплаченным. Ответы на эти вопросы стоят дешевле до запуска, чем после.
Kaspi Pay закрывает казахстанскому магазину значительную часть аудитории, но он не единственный способ оплаты, который стоит держать на сайте. Про то, как он сочетается с интернет-эквайрингом и другими вариантами, мы отдельно писали в материале про интеграцию 1С-Битрикс с платёжными системами Казахстана. Правильный набор для конкретного магазина обычно определяется не технологией, а тем, чем реально платят его покупатели.
Частые вопросы
Есть ли готовый модуль Kaspi Pay для 1С-Битрикс?
Готового модуля именно для приёма оплаты Kaspi на собственном сайте в маркетплейсе 1С-Битрикс нет. По запросу Kaspi там находится решение для обмена товарами и заказами с маркетплейсами, включая площадку Kaspi, но это другая задача. Приём оплаты на сайте делается собственным обработчиком платёжной системы.
Можно ли принимать оплату Kaspi без разработки вообще?
Можно. Kaspi Pay даёт счёт для оплаты и оплату по ссылке, их продавец формирует сам и отправляет покупателю. Сайт при этом не знает о факте оплаты, статусы заказов менеджер закрывает вручную. Для небольшого потока заказов этого хватает.
Где взять документацию по API?
На сайте платёжной системы Kaspi опубликован технический регламент, но он описывает подключение участника платёжной системы, то есть стороннего мобильного приложения. Материалы для интеграции интернет-магазина Kaspi предоставляет в рамках договора, поэтому запрашивать их нужно у банка.
Сколько занимает интеграция?
Работа на стороне сайта обычно заметно короче, чем согласование с банком. Ручной и полуавтоматический сценарии запускаются за несколько дней. Срок полной интеграции определяется тем, как быстро вы получите договор и технические материалы, поэтому планировать её стоит с этого шага, а не с оценки разработки.
Что делать с возвратами?
Возврат в 1С-Битрикс реализуется через интерфейс IReturn в обработчике платёжной системы, чтобы менеджер работал из карточки заказа. В самой платёжной системе Kaspi возврат вынесен в отдельный метод и обязателен для участников системы, так что условия возврата стоит проговорить с банком на этапе договора.