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