Интеграция платежной системы Белкарт в мобильное приложение
Белкарт — национальная платёжная система Беларуси, и её интеграция в мобильное приложение немного отличается от привычных Stripe или Checkout.com. Прямого публичного SDK нет — Белкарт работает через банки-эквайеры (Беларусбанк, БПС-Сбербанк, Приорбанк, и другие), и у каждого свои API и документация. Это первое, что нужно выяснить до начала разработки.
Где обычно спотыкаются
Самая частая ситуация: клиент говорит «интегрируй Белкарт», а конкретного банка-эквайера ещё нет. Без договора эквайринга нет API-ключей, без ключей — нет тестовой среды. Интеграция блокируется не технически, а организационно. Берём паузу на получение credentials, параллельно готовим платёжный модуль приложения под абстрактный интерфейс — PaymentGateway протокол/интерфейс — чтобы потом подставить конкретную реализацию.
Технически: большинство белорусских банков предоставляют платёжную форму через redirect или iframe. Для мобильного приложения это означает SFSafariViewController на iOS или Custom Tabs на Android — точно так же, как WebView-интеграция iPay. Нативного SDK у банков нет — работаем с REST API и WebView-формой.
Специфика Белкарт-карт: 3D-Secure обязателен. Это означает, что redirect на страницу подтверждения банка — неизбежная часть флоу. Если приложение пытается обработать 3DS в обычном WKWebView без SFSafariViewController, cookies банковской страницы могут не сохраниться между переходами, и 3DS зависнет. Используем SFSafariViewController или корректно настраиваем WKWebView с разрешением cross-site cookies (allowsBackForwardNavigationGestures, правильный navigationDelegate).
Как строим интеграцию
Флоу: приложение создаёт заказ на своём сервере → сервер обращается к API банка-эквайера (REST, обычно HTTPS POST с JSON или form-encoded параметрами) → получает URL платёжной формы → передаёт URL мобильному клиенту → клиент открывает форму в SFSafariViewController / Custom Tabs.
После оплаты банк делает redirect на returnUrl — специфический URL вашего приложения (yourapp://payment/result). На iOS обрабатываем через Universal Links или URL Scheme в AppDelegate. Параллельно сервер получает webhook-уведомление от банка — это основной источник истины для статуса транзакции.
Верификация подписи webhook — обязательна. Беларусбанк и БПС используют HMAC-SHA1 или SHA256 с секретным ключом. Если не проверять — любой может отправить фейковый payment.success на ваш endpoint.
На Android нюанс с Custom Tabs: если на устройстве нет Chrome, Custom Tabs не запустятся, WebView используется как fallback. Тестируем на устройствах с MIUI/One UI, где Chrome не системный браузер.
Дополнительно по безопасности
Белкарт-транзакции содержат PAN (номер карты) в masked виде — не логируем даже маскированный PAN в Crashlytics или Firebase Analytics. Данные транзакции хранятся только на сервере, клиентское приложение работает только с orderId и статусом.
Процесс
Заключение договора эквайринга с банком → получение тестовых credentials → разработка серверной части (создание заказа, webhook) → мобильный платёжный модуль → тестирование 3DS флоу на реальных Белкарт-картах → production → мониторинг первых транзакций.
Ориентиры по срокам
Сама интеграция — 2–3 дня после получения API-документации и тестовых ключей. Ожидание договора с банком не входит в оценку разработки.