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
| Aspect | Decentralized (payment in each mini-program) | Centralized (single module in Shell) |
|---|---|---|
| PCI DSS scope | Expands to every mini-program | Limited to Shell App — one audit |
| Key/certificate updates | Requires deploy of all mini-programs | Only Shell App needs update |
| Unified payment history | None | Available in Shell for all mini-programs |
| Payment UI/UX | Different per mini-program | Consistent, increases trust |
| Time to onboard new mini-program | 1–3 weeks | 1–3 days (just bridge API call) |
Centralization cuts effort by 5–10x per mini-program and minimizes risks during PCI DSS audits.
Provider Comparison: When Routing is Needed
| Scenario | Single Provider | Multiple Providers with Routing |
|---|---|---|
| All mini-programs use one acquirer | Yes, sufficient | Overkill |
| Different product categories (marketplace vs finance) | No flexibility | Yes, routing by miniProgramId |
| Fallback on provider failure | No | Yes, automatic switch |
| Commission optimization | No | Choose lowest commission |
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
orderIdon 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
orderIdat 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
- Analysis of your Super App architecture and number of mini-programs.
- Design of bridge API (iOS/Android) and contracts for
PaymentRequest/PaymentResult. - Implementation of
PaymentCoordinatorwith support for one or multiple providers. - Development of unified payment UI (Bottom Sheet) with Apple Pay, Google Pay, SBP, cards.
- Integration of tokenization and saved payment methods.
- Testing with two pilot mini-programs.
- Documentation of the bridge API for mini-program developers.
- 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.