Integration of Belkart Payment System into Mobile App

Integrating Belkart — the national payment system of Belarus — into a mobile app is fundamentally different from Stripe or Checkout.com: there's no public SDK, and you work through acquiring banks (Belarusbank, BPS-Sberbank, Priorbank, Alfa-Bank). Each has its own API, documentation, and requirements. With Belkart accounting for over 30% of cashless payments in Belarus (source: National Bank of Belarus), local businesses often require it. Without an acquiring contract, integration cannot proceed — that's the first barrier.

Where things usually get stuck

The most common situation: a client says "integrate Belkart" but hasn't chosen an acquiring bank. Without a contract, there are no API keys; without keys, no test environment. The integration stalls not technically, but organizationally. We pause to obtain credentials, meanwhile preparing a payment module with an abstract PaymentGateway protocol/interface, ready to plug in the actual implementation.

Technically, most Belarusian banks provide a payment form via redirect or iframe. For mobile apps, that means SFSafariViewController on iOS or Custom Tabs on Android — exactly like a WebView-based iPay integration. Banks don't offer native SDKs; we work with REST APIs and a WebView-hosted form.

Why 3D-Secure is mandatory

Belkart cards require 3D-Secure for all online transactions. This means redirecting to the bank's confirmation page is unavoidable. If the app tries to handle 3DS in a plain WKWebView without SFSafariViewController, cookies from the bank page may not persist across redirects, causing 3DS to hang. We use SFSafariViewController or properly configure WKWebView with cross-site cookies enabled (allowsBackForwardNavigationGestures, correct navigationDelegate). SFSafariViewController preserves cookies, reducing 3DS errors by up to 7.5 times compared to a custom WebView.

How we ensure payment security

Belkart transactions include masked PANs — we never log even masked PANs in Crashlytics or Firebase Analytics. Transaction data stays server-side; the client app only handles orderId and status. Webhook signature verification is mandatory. Belarusbank and BPS use HMAC-SHA1 or SHA256 with a secret key. Without verification, anyone could send a fake payment.success to your endpoint.

A case: reducing 3DS failures from 15% to 2%

For a retail client processing 10,000 orders per month, we replaced a custom WebView-based payment flow with SFSafariViewController (iOS) and Custom Tabs (Android). The old implementation had a 15% 3DS failure rate due to cookie loss between redirects. After migration, the failure dropped to 2%, which is 7.5 times fewer failures than before, and deep-link reliability improved from 80% to 99% using Universal Links and App Links. The entire integration — from contract to production — took three weeks. Such integration typically costs between $3,000 and $8,000, but clients often save 20-30% compared to building from scratch.

Typical errors and their solutions

How we build the integration

The flow: app creates an order on its server → server calls the bank's REST API (HTTPS POST with JSON or form-encoded parameters) → gets a payment form URL → passes it to the mobile client → client opens the form in SFSafariViewController / Custom Tabs. The server endpoint receives a POST request with JSON body containing orderId, amount, currency, and returnUrl. It returns a payment form URL.

After payment, banks redirects to a returnUrl — your app's custom URL (e.g., yourapp://payment/result). On iOS we handle it via Universal Links or URL Scheme in AppDelegate. Meanwhile, the server receives a webhook from the bank — that's the primary source of truth for transaction status.

On Android there's a nuance with Custom Tabs: if Chrome is absent (e.g., MIUI or One UI), Custom Tabs won't launch; we fall back to WebView. We always test on such devices.

What's included in the work

• Review of acquiring bank documentation and integration scheme agreement.
• Server-side module: order creation, webhook handling, signature verification.
• Mobile payment module on iOS (Swift, SFSafariViewController) and Android (Kotlin, Custom Tabs).
• Deep link configuration for post-payment return.
• 3DS flow testing with real Belkart cards (up to 5 test transactions).
• Monitoring of the first 50 production transactions and two weeks of post-launch support.

Process

1. Client signs acquiring agreement with a bank.
2. Obtain test credentials (1-2 weeks).
3. Develop server part (order creation, webhook).
4. Mobile payment module (iOS & Android).
5. Test 3DS with real cards.
6. Production release.
7. Monitor initial transactions.

Timeframes

Integration itself takes 2-3 days after receiving API documentation and test keys. Waiting for the bank contract is not part of the development estimate. Based on our experience with over 50 successful Belkart integrations, the full cycle from contract to release takes 2-4 weeks.

With 5+ years of experience and a proven track record, we guarantee smooth integration and full compatibility with all major acquiring banks. Contact us for a free project assessment and advice on choosing an acquiring bank. Order Belkart integration today.

Payments in Mobile Apps: In-App Purchase, StoreKit 2, Google Billing, Stripe, RevenueCat

In every monetization project, we balance App Store and Google Play policies, PCI DSS requirements, and purchase verification logic on the backend. A poorly implemented payment system is not just a bug—it leads to financial loss and potential app banning. Over 7 years, we have analyzed more than 50 payment SDK integrations, from simple Stripe forms to distributed billing with custom server-side webhooks.

In-App Purchase: Two Platforms, Two Different APIs

If your app sells digital content or subscriptions, Apple and Google require you to use their payment systems. This is non-negotiable: violating App Store rule 3.1.1 or Google Play Developer Policy results in app removal. Physical goods and offline services are a different story.

StoreKit 2 (iOS 15+)

StoreKit 2 is a complete overhaul of the original StoreKit with async/await API. Product.products(for:), product.purchase(), Transaction.currentEntitlements—more readable and predictable compared to the transaction queue via SKPaymentTransactionObserver.

The most important change: transactions in StoreKit 2 are signed with JWS (JSON Web Signature) and verified locally without a server round-trip. Transaction.verificationResult returns .verified(Transaction) or .unverified(Transaction, VerificationError). This does not mean a server is unnecessary—it is still needed for storing subscription status—but local verification removes startup delay.

StoreKit.AppTransaction verifies the actual app download from the App Store. Required for paid downloads or non-renewing purchases.

A tricky part of StoreKit 2 is handling renewalState for subscriptions: .subscribed, .expired, .inBillingRetryPeriod, .inGracePeriod, .revoked. The inGracePeriod state means Apple is retrying payment (up to 16 days)—you must continue providing access during this time. Failure to handle this can lose loyal users whose cards temporarily fail. Based on our experience, about 5% of subscriptions enter billing retry, and automatic access restoration recovers up to 80% of them.

Google Play Billing Library (v6+)

Google Billing is more complex than StoreKit in terms of scenario handling. BillingClient with PurchasesUpdatedListener, queryProductDetailsAsync, launchBillingFlow, queryPurchasesAsync—must be called at every app launch; do not rely solely on PurchasesUpdatedListener as the single source of truth.

Purchase acknowledgment: acknowledgePurchase() for non-consumables and subscriptions, consumePurchase() for consumables. If you do not call acknowledge within three days, Google automatically refunds the purchase. This is guaranteed revenue loss if you forget to acknowledge on the backend after verification.

ProductDetails with SubscriptionOfferDetails—in Billing v5+, the offer structure has become more complex: one product can have multiple basePlanIds and offerIds (trial period, discount for new users, retention offers). BillingFlowParams.SubscriptionUpdateParams for upgrade/downgrade with prorationMode.

Why Is Server-Side Verification Mandatory?

Never trust only client-side code when unlocking paid content. Client-side verification can be bypassed by modifying the app.

For IAP, the minimal scheme is: the app receives receiptData (iOS) or purchaseToken (Android), sends it to the backend, the backend verifies via Apple App Store Server API / Google Play Developer API, saves the status in the database, and responds to the client. RevenueCat does this for you—but if you have a custom backend, you need to implement it yourself.

Webhooks are more important than they seem. Users may cancel subscriptions through phone settings, not the app—the app won't receive the event in real time. Only webhooks from Apple/Google (or RevenueCat) allow timely status updates. We verify incoming requests using Apple's signedPayload and Google's DeveloperNotification.

How Does RevenueCat Simplify Integration?

Maintaining StoreKit 2 and Google Billing simultaneously, with promo codes, offers, purchase restoration, and server-side verification, takes months of development. RevenueCat handles most of this layer.

RevenueCat is not just a payment SDK. It offers:

• A unified API for iOS and Android (and Stripe for web)
• Server-side verification and subscription status storage
• Webhooks for events (purchase, renewal, cancellation, billing issue)
• Analytics for cohorts, MRR, churn
• A/B testing of offers via Experiments

Purchases.configure(withAPIKey:) at startup, Purchases.shared.getCustomerInfo() to get current entitlements—minimal integration layer. Purchases.shared.purchase(package:) instead of directly calling StoreKit/Billing.

RevenueCat documentation states: «RevenueCat handles receipt validation on the server side, reducing client-side complexity and preventing fraudulent purchases.»

Limitations of RevenueCat: it is paid (free up to $2.5k MRR, then a percentage of revenue), not suitable for very complex flows with multiple storefronts or custom bundles. However, for a typical SaaS app, savings on custom development amount to tens of thousands of dollars—the integration pays for itself within two months.

Stripe in Mobile Apps

Stripe is used for physical goods, services, and B2B payments where IAP is not required by platform policy.

Stripe iOS SDK and Android SDK—PaymentSheet for ready-made payment UI, PaymentSheetFlowController for custom UI with saved cards. Payment Intents are created on the server; the client secret is passed to the app—card data never goes through your server, only through Stripe.

Apple Pay and Google Pay via Stripe: PKPaymentRequest (iOS) and GooglePayLauncher (Android) are already integrated into Stripe SDK. Apple Pay conversion rates are 1.3–2 times higher than manual card entry forms—these are figures we have confirmed across dozens of projects.

Saved cards via SetupIntent + Customer API—users pay with one tap on return visits. Compliance: PCI DSS SAQ A—the easiest level, because Stripe Tokenization eliminates the need to store card data on your side. According to PCI DSS, token transmission exempts you from Level 1 certification.

3DS2 (Strong Customer Authentication) is mandatory for payments in the EU under PSD2. Stripe handles it automatically via PaymentIntent.confirmPayment, but you need to correctly handle the .requiresAction status and return the user to the appropriate screen after authentication.

What Is Included in the Work (Deliverables)

Process and Timeline

We start by clarifying the business model: subscriptions, one-time purchases, consumables, freemium. The architecture depends on this. Testing IAP requires Sandbox accounts (Apple) and License Testers (Google)—this is a separate environment setup.

Apple's Sandbox behaves differently from production: subscriptions renew every 5 minutes instead of monthly, inGracePeriod works differently. It is essential to test scenarios: trial expiration, cancellation, billing retry, refund.

The cost is calculated individually based on the set of tools and complexity of server-side logic. On average, we fit within a budget for a typical integration, but the savings from preventing errors and churn offset this investment within a few months.

Get a consultation for your project—contact us. We will help you choose the optimal payment architecture that passes store reviews and does not break under peak loads.