Halva Installment Integration in Mobile Application
Halva (Sovkombank) is an installment card which internet shops add as alternative to "buy now, pay later". In mobile app integration is built on Halva's REST API and deeplink transition to Halva app — if installed on device.
Two Scenario Flows
Halva app installed. User clicks "Pay with Halva Installment" → your app opens deeplink halva://partner/pay?orderId=...&amount=...&token=... → user sees confirmation screen in Halva app → confirms → Halva returns user via deeplink-callback to your app → server gets webhook about application status.
App not installed. Fallback to WebView form: open SFSafariViewController / Custom Tabs with Halva web form URL. Flow is same, just via browser.
Check app presence on iOS: UIApplication.shared.canOpenURL(URL(string: "halva://")!). Important: from iOS 9 need to add halva in LSApplicationQueriesSchemes in Info.plist, otherwise canOpenURL always returns false regardless of app presence. One of most common misses.
Installment Calculation
Before checkout user wants to see payment schedule: "12 months — X rubles/month". Halva provides /v1/installment/calculate API with amount and partnerId parameters. Response: list of available installment periods with payment amounts. Display as picker/chip component — user selects term, app updates monthly payment in realtime.
Cache calculation response for 10–15 minutes — installment terms don't change by minute, extra network requests slow UX.
Server Side
Mobile client must not call Halva API directly with secret keys. All flow via your server: application creation → token/URL receipt → client transmission. Halva webhook (application.approved / application.rejected) handled by server, changes order status, sends push to user.
Push on approval — important UX detail. User went to Halva app, returned, but didn't wait for answer. Push via Firebase Cloud Messaging (FCM) / APNs brings them back to order completion.
Typical Mistakes
- Deeplink callback not handled at cold start (user swiped app from memory, Halva opens deeplink — app launches from zero, callback lost). Solution: save orderId in UserDefaults/SharedPreferences, on startup check pending applications.
- Don't handle
application.expired— application approved, but user didn't confirm within 30 minutes. Need timer and corresponding UI.
Flutter and React Native
On Flutter: deeplink handled via uni_links package. getInitialLink() at cold start, linkStream for foreground. On app start — check getInitialLink() for Halva callback presence, if yes — restore order context from SharedPreferences and show correct status screen.
On React Native: Linking.getInitialURL() + Linking.addEventListener('url', handler). Logic same — pending orderId stored in AsyncStorage.
Timeline Estimates
Full integration with installment calculation, deeplink flow and WebView fallback: 2–3 days. For Flutter/React Native with proper cold start handling — plus half day on Linking debugging.