Підключаємо розстрочку Халва: повний цикл у мобільному додатку
При інтеграції розстрочки Халва в мобільний додаток ми стикаємося з двома принципово різними сценаріями: чи встановлено додаток Халви на пристрої користувача. Наш підхід базується на REST API Халви та обробці deeplink-переходів. За 5 років роботи ми виконали понад 30 інтеграцій з платіжними сервісами та гарантуємо стабільну роботу. Одна з таких інтеграцій допомогла інтернет-магазину збільшити конверсію на 18% за рахунок спрощення процесу оплати.
Як перевірити, чи встановлено Халву на пристрої?
Перевірка наявності додатку Халви — перший крок. На iOS використовуємо UIApplication.shared.canOpenURL(URL(string: "halva://")!). Важно: з iOS 9 потрібно додати halva в LSApplicationQueriesSchemes в Info.plist, інакше canOpenURL завжди поверне false. Це одна з найчастіших помилок, які ми виправляємо при аудиті. Згідно з документацією Apple Developer про canOpenURL, необхідно вказувати схеми заздалегідь. На Android перевірка виконується через PackageManager.getPackageInfo().
Два сценарії флоу
Додаток Халви встановлено. Користувач натискає «Оплатити в розстрочку Халва» → ваш додаток відкриває deeplink halva://partner/pay?orderId=...&amount=...&token=... → користувач бачить екран підтвердження в додатку Халви → підтверджує → Халва повертає користувача через deeplink-callback у ваш додаток → сервер отримує webhook про статус заявки.
Додаток не встановлено. Fallback на WebView-форму: відкриваємо SFSafariViewController / Custom Tabs з URL web-форми Халви. Флоу той самий, тільки через браузер.
| Параметр | Deeplink-сценарій | WebView fallback |
|---|---|---|
| Швидкість | ~3 секунди до підтвердження | ~10 секунд (завантаження форми) |
| UX | Нативний екран Халви | Браузерний інтерфейс |
| Технічна складність | Вимагає обробки callback при cold start | Простіше, але повільніше |
Deeplink-сценарій у 3 рази швидший за WebView-форму за часом підтвердження, тому його реалізація критична для конверсії.
Розрахунок розстрочки
Перед оформленням користувач хоче бачити графік платежів: «12 місяців — X грн/міс». Халва надає API /v1/installment/calculate з параметрами amount та partnerId. Відповідь: список доступних періодів розстрочки з сумами платежів. Відображаємо у вигляді picker/chip-компонента — користувач обирає термін, додаток оновлює суму щомісячного платежу в реальному часі.
Кешуємо відповідь розрахунку на 10–15 хвилин — умови розстрочки не змінюються щохвилини, а зайві мережеві запити сповільнюють UX.
Чому обробка webhook критична для UX?
Мобільний клієнт не повинен напряму звертатися до API Халви з секретними ключами. Весь flow через ваш сервер: створення заявки → отримання токена/URL → передача клієнту. Webhook від Халви (application.approved / application.rejected) обробляє сервер, змінює статус замовлення, надсилає push-сповіщення користувачеві.
Push при схваленні заявки — важлива деталь UX. Користувач пішов у додаток Халви, повернувся, але не дочекався відповіді. Push через Firebase Cloud Messaging (FCM) / APNs повертає його до завершення замовлення.
Типові помилки при інтеграції
- Deeplink callback не оброблений при cold start додатку (користувач свайпнув додаток з пам'яті, Халва відкриває deeplink — додаток запускається з нуля, callback втрачається). Рішення: зберігаємо orderId в UserDefaults/SharedPreferences, при старті перевіряємо pending-заявки.
- Не обробляємо
application.expired— заявка схвалена, але користувач не підтвердив протягом 30 хвилин. Потрібен таймер і відповідний UI.
Як налаштувати deeplink-інтеграцію: покроково
- Зареєструйте deeplink-схему
halva://в маніфесті Android (intent-filter) і в Info.plist iOS (CFBundleURLSchemes). - На сервері створіть endpoint для отримання webhook-статусів від Халви.
- На клієнті реалізуйте обробку deeplink:
getInitialLink/getInitialURLдля cold start, stream/subscription для foreground. - Зберігайте orderId при відкритті deeplink, щоб відновити контекст при cold start.
- Протестуйте на реальних пристроях з встановленим і невстановленим додатком Халви.
Більше деталей в офіційній документації Халви. Зв'яжіться з нами для отримання інструкції.
Flutter та React Native
| Платформа | Пакет | Cold start | Foreground |
|---|---|---|---|
| Flutter | uni_links |
getInitialLink() |
linkStream |
| React Native | Linking | getInitialURL() |
addEventListener('url') |
На Flutter: deeplink обробляється через uni_links пакет. getInitialLink() при cold start, linkStream для foreground. При старті додатку — перевіряємо getInitialLink() на наявність Халва-callback, якщо є — відновлюємо контекст замовлення з SharedPreferences і показуємо правильний екран статусу.
На React Native: Linking.getInitialURL() + Linking.addEventListener('url', handler). Логіка та ж — pending orderId зберігається в AsyncStorage.
Що входить в роботу
- Інтеграція API розрахунку розстрочки з кешуванням
- Реалізація deeplink-флоу з cold start обробкою
- WebView fallback для пристроїв без додатку Халви
- Серверна частина: webhook endpoint, push-сповіщення
- Документація по інтеграції та тестування на 3+ пристроях
- Підтримка при релізі в App Store та Google Play
Орієнтири за термінами
Повна інтеграція з розрахунком розстрочки, deeplink-флоу та WebView-fallback: 2–3 дні. Для Flutter/React Native з правильною обробкою cold start — плюс півдня на налагодження Linking. Оцінимо ваш проект безкоштовно — зв'яжіться для консультації. Отримайте готову інтеграцію під ключ з гарантією стабільної роботи. Замовте прямо зараз — ми передзвонимо протягом години.