Karta Pokupok Installment Integration in Mobile Application
"Karta Pokupok" is a Belarusian installment product which stores add to increase average check. Unlike Russian Halva, there is no separate mobile app from issuer — flow is entirely via WebView form and server API.
How Flow Works
User selects "Pay with Installment" → your server creates application via Karta Pokupok API, gets payment form URL → mobile app opens URL in SFSafariViewController (iOS) / Custom Tabs (Android) → user enters card details and confirms → redirect to successUrl/failUrl → webhook to your server about final status.
Nuance: Karta Pokupok form uses OTP confirmation via SMS. In SFSafariViewController SMS AutoFill (iOS 12+) works natively — Safari offers to insert code from message. In regular WKWebView this also works with proper contentType = .oneTimeCode in form. Make sure not blocking JavaScript in WebView.
Calculation and Display of Terms
API provides installment calculation endpoint: send amount, get available periods (3, 6, 12 months) and monthly payment. Display before opening form — user must see terms before clicking button.
Example response: {"periods": [{"months": 6, "monthly": 83.33}, {"months": 12, "monthly": 41.67}]}. Show as horizontal list with period selection chips — standard UX for BNPL products.
Status Handling
Karta Pokupok returns three final statuses: approved, rejected, cancelled. rejected — bank denied installment — show message with card payment offer. Don't write "error" — write "Bank denied installment. You can pay by card". Difference in conversion is noticeable.
Callback via returnUrl handled in AppDelegate/Application by URL scheme. In parallel — webhook to server. Get status from webhook, not from returnUrl query parameters (can be faked).
Typical Implementation Mistakes
Plain WKWebView instead of SFSafariViewController. In WKWebView no access to system Safari cookies. If Karta Pokupok uses cookie-based session on its form, user each time will go through authorization anew. SFSafariViewController solves this — it shares cookie storage with Safari.
Not handling application timeout. Installment application active for limited time (usually 15–30 minutes). If user left form screen and returned in hour — show "Session time expired, try again" instead of hanging spinner.
No retry on temporary API unavailability. Application creation — critical request. On 503/504 from Karta Pokupok server — Exponential Backoff with three attempts before showing error to user.
Process
Partner contract activation → test credentials → server module (application creation, webhook) → mobile part (WebView flow, deeplink handling) → testing with test card data → production.
Timeline Estimates
2–3 days from API key receipt. Organizational part (partner contract) — out of development estimate.







