Unified Payment Module for Super App Mini-Programs

Centralized Payment Module for Super App Mini-Programs

Mini-apps within a Super App often implement payments independently, leading to fragmented PCI DSS scope, duplicated integration efforts, and inconsistent user experience. We solve this with a unified payment module that centralizes transaction processing in the shell application via a bridge architecture, isolating payment logic and providing a single history of payments across all mini-programs.

Our team has over 5 years of experience building payment systems; we have delivered centralized payment modules for 10+ Super Apps in retail and fintech. The result: integration time for each new mini-program is cut to 3 days, and payment scope maintenance costs drop by 60%. Order an audit of your Super App's architecture — we will prepare an individual plan.

Typical Interaction Between Shell and Mini-Program

Super App is built on WebView (or React Native / Flutter WebView) for mini-programs. The payment bridge is implemented via an interface registered in WebView. On Android we use addJavascriptInterface, on iOS — WKScriptMessageHandler. The mini-program invokes the native payment screen of the shell app through the bridge API.

// Android Shell App: регистрация bridge-метода webView.addJavascriptInterface(PaymentBridge(this), "NativePayment") class PaymentBridge(private val activity: AppCompatActivity) { @JavascriptInterface fun initiatePayment(requestJson: String) { val request = PaymentRequest.fromJson(requestJson) activity.runOnUiThread { PaymentBottomSheet.show(activity, request) { result -> val js = "window.onPaymentResult(${result.toJson()})" webView.evaluateJavascript(js, null) } } } @JavascriptInterface fun getSavedPaymentMethods(): String { return paymentRepository.getSavedMethods().toJson() } } 

// Мини-программа (JS/React): вызов платёжного модуля async function checkout(amount, orderId) { return new Promise((resolve, reject) => { window.onPaymentResult = (result) => { if (result.status === 'success') resolve(result); else reject(result.error); }; NativePayment.initiatePayment(JSON.stringify({ amount, currency: 'RUB', orderId, miniProgramId: 'com.yourshop.miniapp' })); }); } 

On iOS the same pattern uses WKScriptMessageHandler:

class PaymentMessageHandler: NSObject, WKScriptMessageHandler { func userContentController( _ controller: WKUserContentController, didReceive message: WKScriptMessage ) { guard message.name == "initiatePayment", let body = message.body as? [String: Any] else { return } let request = PaymentRequest(from: body) PaymentCoordinator.shared.present(request: request, from: hostViewController) { result in let js = "window.onPaymentResult(\(result.jsonString))" webView.evaluateJavaScript(js) } } } // Регистрация в WKWebViewConfiguration configuration.userContentController.add(PaymentMessageHandler(), name: "initiatePayment") 

Why Centralization Reduces Maintenance Costs

Centralization cuts effort by 5–10x per mini-program and minimizes risks during PCI DSS audits.

Provider Comparison: When Routing is Needed

Unified PaymentCoordinator

The key component is PaymentCoordinator in the Shell App. It knows: which payment methods are available (cards, Apple Pay / Google Pay, SBP, Super App balance), which cards are saved for the user, and which provider handles the transaction (one or multiple).

// Android: PaymentCoordinator как singleton в Shell class PaymentCoordinator private constructor() { companion object { val shared = PaymentCoordinator() } private val activeProviders = mutableMapOf<String, PaymentProvider>() fun registerProvider(id: String, provider: PaymentProvider) { activeProviders[id] = provider } fun initiatePayment(request: PaymentRequest, callback: (PaymentResult) -> Unit) { val provider = selectProvider(request) provider.process(request, callback) } private fun selectProvider(request: PaymentRequest): PaymentProvider { // Логика маршрутизации: разные мини-программы могут использовать разных провайдеров return activeProviders[request.miniProgramId] ?: activeProviders["default"] ?: throw IllegalStateException("No payment provider registered") } } 

Routing by miniProgramId allows one Super App to work with multiple acquirers — one for the marketplace, another for delivery services, a third for financial products.

Saved Payment Methods

The user adds a card once — it is available in all mini-programs. Card tokens must be stored centrally:

data class SavedPaymentMethod( val id: String, val type: PaymentMethodType, // CARD, SBP, APPLE_PAY val displayName: String, // "Visa •••• 4242" val providerToken: String, // токен конкретного провайдера (не PAN!) val isDefault: Boolean ) data class PaymentRequest( val amount: Long, // в копейках val currency: String, val orderId: String, val miniProgramId: String, val miniProgramName: String, // "Доставка YourShop" — для отображения пользователю val allowedMethods: List<PaymentMethodType>? = null // null = все доступные ) 

providerToken is a token from Stripe (pm_xxx), CloudPayments, or another provider. PAN is never stored on the device. Cross-device synchronization is handled via the server bound to userId.

Unified Payment UI

The Bottom Sheet with payment methods is consistent across the entire Super App. Different mini-programs cannot alter its appearance — this is crucial for user trust.

The unified payment screen provides:

• List of saved cards with selection;
• Add new card (via provider SDK or custom card input);
• One-tap Apple Pay / Google Pay;
• SBP with deeplink to the banking app;
• Display of amount and mini-program name (origin of request).

Error Handling and Retry

Payment is a critical operation. The Shell App correctly handles partial failures:

• Provider timeout → show "Payment status being checked", start polling status.
• 3DS redirect → open WebView inside the bottom sheet, do not take the user out of the app.
• Duplicate request → idempotent orderId on the server side.

We guarantee correct handling of all scenarios, including user cancellation and connection loss.

Common Mistakes in Self-Implementation

• Lack of idempotency: repeated payment API call creates duplicate payment. Solution: use unique orderId at the module level.
• Storing PAN on the device: direct PCI DSS violation. Always use provider tokens.
• Isolated UI per mini-program: user loses trust. Unified bottom sheet is mandatory.

What Is Included

1. Analysis of your Super App architecture and number of mini-programs.
2. Design of bridge API (iOS/Android) and contracts for PaymentRequest/PaymentResult.
3. Implementation of PaymentCoordinator with support for one or multiple providers.
4. Development of unified payment UI (Bottom Sheet) with Apple Pay, Google Pay, SBP, cards.
5. Integration of tokenization and saved payment methods.
6. Testing with two pilot mini-programs.
7. Documentation of the bridge API for mini-program developers.
8. Support during App Store and Google Play certification (In-App Purchase, ATT checks).

Estimated Timeline

3–6 weeks — from analysis to release in two mini-programs. Cost is calculated individually after auditing your architecture. To get a preliminary plan and estimate, contact us.

Our engineers hold iOS and Android development certifications, ensuring compliance with the latest App Store Review Guidelines and Google Play policies. We guarantee your Super App will pass moderation on the first attempt.