Белкарт — національна платіжна система Білорусі. Інтеграція в мобільний застосунок принципово відрізняється від 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 тижні.
Зв’яжіться — оцінимо ваш проєкт. Отримайте консультацію щодо вибору банку-еквайера. Замовте інтеграцію Белкарт вже сьогодні.
