Белкарт — национальная платёжная система Беларуси. Интеграция в мобильное приложение принципиально отличается от Stripe или Checkout.com: нет публичного SDK, работа идёт через банки-эквайеры (Беларусбанк, БПС-Сбербанк, Приорбанк, Альфа-Банк). У каждого свои API, документация и требования. По данным Национального банка, доля Белкарт в безналичных платежах превышает 30%, поэтому для локальных бизнесов подключение этой системы стало обязательным. Без договора эквайринга интеграция не сдвинется с места — это первое, что нужно выяснить до начала разработки.
Где обычно спотыкаются
Самая частая ситуация: клиент говорит «интегрируй Белкарт», а конкретного банка-эквайера ещё нет. Без договора нет API-ключей, без ключей — нет тестовой среды. Интеграция блокируется не технически, а организационно. Мы берём паузу на получение credentials, параллельно готовим платёжный модуль приложения под абстрактный интерфейс — PaymentGateway протокол/интерфейс — чтобы потом подставить конкретную реализацию.
Технически: большинство белорусских банков предоставляют платёжную форму через redirect или iframe. Для мобильного приложения это означает SFSafariViewController на iOS или Custom Tabs на Android — точно так же, как WebView-интеграция iPay. Нативного SDK у банков нет — работаем с REST API и WebView-формой.
Почему 3D-Secure обязателен?
Специфика Белкарт-карт: 3D-Secure обязателен для всех онлайн-транзакций. Это означает, что redirect на страницу подтверждения банка — неизбежная часть флоу. Если приложение пытается обработать 3DS в обычном WKWebView без SFSafariViewController, cookies банковской страницы могут не сохраниться между переходами, и 3DS зависнет. Используем SFSafariViewController или корректно настраиваем WKWebView с разрешением cross-site cookies (allowsBackForwardNavigationGestures, правильный navigationDelegate). SFSafariViewController обеспечивает сохранение cookies до 3 раз реже возникают ошибки 3DS по сравнению с кастомным WebView.
Как обеспечить безопасность транзакций Белкарт?
Белкарт-транзакции содержат PAN (номер карты) в masked виде — не логируем даже маскированный PAN в Crashlytics или Firebase Analytics. Данные транзакции хранятся только на сервере, клиентское приложение работает только с orderId и статусом. Верификация подписи webhook — обязательна. Беларусбанк и БПС используют HMAC-SHA1 или SHA256 с секретным ключом. Если не проверять — любой может отправить фейковый payment.success на ваш endpoint.
| Компонент | iOS | Android |
|---|---|---|
| Платёжная форма | SFSafariViewController | Custom Tabs (fallback WebView) |
| Глубокие ссылки | Universal Links / URL Scheme | App Links / intent |
| Пуш-уведомления | APNs (через сервер) | FCM (через сервер) |
| Логирование | Ограниченное (без PAN) | Ограниченное (без PAN) |
Типичные ошибки и их решение
| Ошибка | Причина | Решение |
|---|---|---|
| 3DS не срабатывает | Cookies не сохраняются между переходами | Использовать SFSafariViewController или настроить WKWebView с cross-site cookies |
| Webhook не приходит | Неправильный URL или IP не в белом списке | Проверить настройки в личном кабинете банка, добавить IP сервера |
| Redirect не возвращается в приложение | Не настроены deep links | Настроить Universal Links / App Links или URL Scheme |
| Ошибка подписи | Неверный алгоритм или секрет | Сверяться с документацией банка, использовать HMAC-SHA256 |
Как строим интеграцию
Флоу: приложение создаёт заказ на своём сервере → сервер обращается к 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-уведомление от банка — это основной источник истины для статуса транзакции.
На Android нюанс с Custom Tabs: если на устройстве нет Chrome (например, MIUI или One UI), Custom Tabs не запустятся, используется WebView как fallback. Обязательно тестируем на таких устройствах.
Что входит в работу
- Проверка документации банка-эквайера и согласование схемы интеграции.
- Разработка серверного модуля: создание заказа, обработка вебхуков, проверка подписи.
- Реализация платёжного модуля на iOS (Swift,
SFSafariViewController) и Android (Kotlin,Custom Tabs). - Настройка глубоких ссылок для возврата после оплаты.
- Тестирование 3DS-флоу на реальных картах Белкарт (до 5 тестовых транзакций).
- Мониторинг первых 50 транзакций в production и поддержка в течение 2 недель после запуска.
Процесс
- Заключение договора эквайринга с банком (клиент).
- Получение тестовых credentials (1–2 недели).
- Разработка серверной части (создание заказа, webhook).
- Мобильный платёжный модуль (iOS и Android).
- Тестирование 3DS на реальных картах.
- Production-релиз.
- Мониторинг первых транзакций.
Ориентиры по срокам
Сама интеграция — 2–3 дня после получения API-документации и тестовых ключей. Ожидание договора с банком не входит в оценку разработки. По опыту, полный цикл от договора до релиза занимает 2–4 недели.
Свяжитесь — оценим ваш проект бесплатно. Получите консультацию по выбору банка-эквайера. Закажите интеграцию Белкарт уже сегодня.