Интеграция Kaspi Pay в мобильное приложение на Delphi
Подключение платежей Kaspi Pay к мобильному приложению на Delphi требует согласовать три части системы: пользовательский интерфейс, серверную логику и возможности платёжного сервиса. Приложение на FireMonkey может работать на Android и iOS, однако секретные ключи, создание заказа и проверка статуса платежа должны находиться за пределами мобильного клиента.
Для коммерческого проекта важно заранее определить модель оплаты. Это может быть переход к платёжной странице, формирование счёта, оплата по QR-коду или иной сценарий, предусмотренный актуальной документацией Kaspi для бизнеса. Конкретный набор методов зависит от договора продавца, типа аккаунта и доступных API, поэтому перед разработкой нужно подтвердить условия подключения.
Как устроен платёжный сценарий
Обычно пользователь выбирает товар или услугу в приложении, после чего клиент отправляет на сервер состав заказа, сумму и идентификатор покупателя. Сервер проверяет данные, создаёт платёжную сессию или счёт через доступный интерфейс Kaspi Pay и возвращает приложению только безопасные данные для продолжения операции.
Далее пользователь оплачивает заказ в разрешённом канале: на странице оплаты, в приложении Kaspi либо с помощью QR-сценария. После завершения операции сервер получает уведомление или самостоятельно запрашивает состояние транзакции. Мобильное приложение не должно считать платёж успешным только потому, что пользователь вернулся на экран заказа: окончательное решение принимает сервер после проверки статуса.
У каждого заказа должен быть уникальный идентификатор, связанный с внутренней записью в базе данных. Сумму, валюту, состав товаров и назначение платежа следует фиксировать до обращения к провайдеру. Это защищает магазин от ситуации, когда клиент изменяет цену в запросе или повторно отправляет старую платёжную команду.
Архитектура приложения и сервера
В Delphi удобно разделить код на несколько уровней. Формы FireMonkey отвечают за отображение корзины, состояния заказа и сообщений об оплате. Отдельный клиентский модуль выполняет HTTP-запросы, преобразует JSON и обрабатывает сетевые ошибки. Серверная часть создаёт платёжные операции, хранит их результаты и взаимодействует с базой данных.
Такой подход подходит для Android, iOS, Windows и macOS: общий бизнес-код остаётся единым, а различия платформ скрываются в сервисных классах. Для сетевого обмена можно использовать TNetHTTPClient, THTTPClient или собственную обёртку над REST-клиентом. Ответы API следует преобразовывать в типизированные структуры, а не разбирать непосредственно в обработчиках кнопок.
Если сервер написан на PHP, Delphi-приложение обращается к нему через HTTPS API. Такой вариант особенно практичен для небольших интернет-магазинов и каталогов услуг: сервер легко разместить рядом с базой данных, а мобильный клиент не получает доступ к внутренним таблицам. Примеры прикладных решений и разработок можно посмотреть в каталоге проектов, где подобный подход естественно сочетается с кроссплатформенной разработкой.
Подготовка данных и запросов Kaspi Pay
До написания кода нужно изучить документацию конкретного продукта Kaspi для продавцов и получить тестовые реквизиты, если они предусмотрены. В интеграции могут использоваться идентификатор магазина, подпись запроса, токен, адрес API и параметры возврата. Эти значения нельзя хранить в исходниках Delphi, ресурсах APK или настройках мобильного приложения.
Сервер формирует запрос по строгой схеме: передаёт номер заказа, сумму, описание, контактные сведения и адреса для уведомления, если они требуются выбранным методом. Важно соблюдать типы данных. Денежные значения нельзя бездумно передавать как результат операций с Double; лучше использовать десятичную модель на сервере или хранить сумму в минимальных единицах, если это допускает спецификация.
При обработке ответа нужно учитывать как HTTP-код, так и прикладной статус. Успешный ответ транспорта не всегда означает завершённую оплату: операция может находиться в состоянии ожидания, быть отклонённой или требовать повторной проверки. В журнале полезно сохранять технический идентификатор транзакции, время запроса, код ответа и обезличенные диагностические данные.
Сравнение способов запуска оплаты
Выбор сценария определяется тем, что разрешено для конкретного продавца и насколько плавным должен быть пользовательский путь. Один метод может быть удобнее для разовой покупки, другой — для постоянного сервиса с большим количеством заказов.
| Способ | Что делает приложение | Преимущества | Что учесть |
|---|---|---|---|
| Платёжная страница | Открывает защищённый URL | Меньше платёжной логики в клиенте | Нужны корректные возвратные адреса |
| QR-оплата | Показывает или передаёт платёжные данные | Удобна для офлайн-сценариев | Нужно обновлять состояние заказа |
| Счёт или ссылка | Создаёт платёжное намерение на сервере | Подходит для заказов и услуг | Важна защита от повторного использования |
| Проверка статуса | Запрашивает результат операции | Повышает надёжность подтверждения | Требуется серверная идемпотентность |
В Delphi для открытия внешней страницы можно использовать системный браузер через платформенный сервис, а для встроенного сценария — компонент WebBrowser, если это разрешено требованиями выбранного платёжного решения. Встроенный браузер требует дополнительного контроля навигации, обработки возврата и поведения на разных версиях Android и iOS.
Реализация клиентской части на Delphi
Экран оплаты должен явно показывать сумму, номер заказа и текущий статус. После нажатия кнопки приложение отправляет запрос на собственный сервер, блокирует повторное нажатие и отображает индикатор ожидания. Получив ссылку или другой платёжный параметр, клиент запускает нужный сценарий и переводит заказ в состояние «ожидает подтверждения».
Для асинхронных запросов важно не блокировать главный поток FireMonkey. Сетевую операцию можно выполнять через задачу или отдельный поток, а обновление визуальных компонентов возвращать в основной поток. При закрытии формы необходимо отменять незавершённые запросы либо игнорировать их результат, чтобы избежать обращения к уже уничтоженному объекту.
Переход пользователя назад не должен автоматически означать отказ от платежа. После возврата приложение может запросить серверный статус, показать промежуточное состояние и выполнить несколько повторных проверок с увеличивающимся интервалом. Если соединение пропало, заказ остаётся ожидающим, а не переводится в ошибочный без подтверждённого ответа.
Безопасность и проверка результата
Ключевое правило интеграции — мобильное приложение не является доверенной средой. Любой параметр, который пришёл с устройства, нужно проверять на сервере: существование заказа, принадлежность пользователю, сумму, валюту и допустимость текущего состояния. Подписанные уведомления от платёжной системы следует валидировать по официальному алгоритму, не полагаясь на переданное клиентом поле success.
Все соединения должны работать через HTTPS с корректной проверкой сертификата. Логи не должны содержать токены, секретные ключи, полные номера карт или иные платёжные данные. Для защиты API применяются авторизация пользователя, ограничение частоты запросов, проверка тела запроса и безопасное хранение сессий.
Тестирование нужно проводить для успешной оплаты, отмены, истечения времени, повторной отправки, недоступности API и разрыва связи после списания средств. Отдельно проверяются дублирующиеся уведомления: один и тот же callback не должен повторно выдавать товар, начислять бонусы или переводить заказ в другое состояние.
Обработка ошибок и статусов
Пользователю следует показывать понятные сообщения: «платёж ожидает подтверждения», «операция отменена», «сервис временно недоступен» или «заказ уже оплачен». Технический текст исключения не подходит для интерфейса, но его краткий код можно записать в журнал для диагностики. Это особенно важно при работе в сетях с нестабильным мобильным интернетом.
Серверная модель заказа может включать состояния new, payment_pending, paid, cancelled и payment_error. Переходы между ними должны быть разрешены только по определённым правилам. Например, повторная проверка уже оплаченного заказа не должна вернуть его в состояние ожидания, а позднее уведомление об отказе не должно отменить подтверждённую операцию без предусмотренного сценария возврата.
Если API временно не отвечает, сервер может использовать повторные запросы с ограниченным числом попыток. Идемпотентный ключ или уникальный номер операции помогает избежать создания нескольких платежей при повторной отправке. После оплаты система должна отдельно выполнить бизнес-действие: выдать доступ, создать чек, уменьшить остаток товара или отправить уведомление.
Поддержка, возвраты и публикация
До выпуска приложения необходимо описать процедуру возврата денежных средств и порядок сверки платежей. Возврат может выполняться через личный кабинет продавца или отдельный серверный метод, если он доступен для выбранной интеграции. В базе данных следует хранить связь между исходным заказом, транзакцией, возвратом и результатом операции.
Для Android и iOS нужно проверить открытие платёжного сценария, возврат в приложение, работу при свёрнутом процессе и восстановление состояния после перезапуска. Пользователь может оплатить заказ вне приложения, удалить его из памяти или сменить сеть, поэтому актуальный статус должен восстанавливаться с сервера при каждом открытии экрана заказа.
Перед публикацией полезно провести контрольную сверку: реквизиты соответствуют рабочему окружению, тестовые адреса заменены, журналирование очищено от секретов, а политика конфиденциальности описывает обработку платёжных данных. Такая подготовка превращает интеграцию Kaspi Pay в управляемый серверный процесс, а Delphi-клиент оставляет лёгким, переносимым и безопасным для разных платформ.