Mobile wallet app: where payment logic breaks
The peak load in a wallet app is not opening a screen, but the moment an operation is confirmed. The user taps "pay," the network drops for a second, the request is sent again — and now there are two identical charges in the history.
It is precisely in such scenarios that payment logic breaks: balance desync during parallel operations, stuck transactions that sit in "processing" status for days, and double charges when the connection drops. Each of these failures costs trust: the user sees an incorrect balance once — and deletes the app.
The root of the problem is that a mobile wallet app is a thin client that lives on an unstable network, while the money moves on the server.
If the client decides on its own when to retry a request, and the server does not distinguish a retry from a new operation, the balance diverges.
Hence the classic case: the charge went through, the response never reached the client, the client sent a retry — and the operation was executed twice.
The second source of failures is concurrency. The user pays in one window and simultaneously receives a transfer in another; two threads read the same balance, both consider it sufficient, both debit it.
Without locks and a single point of balance accounting, the balance drifts even without connection drops.
The third layer is transaction statuses. The payment went to the acquiring bank, but confirmation was delayed: in the app it is "stuck," while in the back office it has already gone through.
As long as there is no reconciliation and no idempotency keys for each operation, such discrepancies accumulate and surface in support in batches.
We break down how this is closed at the level of payment app development — from request idempotency to state reconciliation and recovery of stuck operations.
Wallet architecture: transaction ledger, reservation, reconciliation
Transaction ledger as the single source of truth
A wallet balance cannot be stored as a single mutable field: under concurrent debits and request retries it inevitably diverges from the history.
That is why we build accounting on an immutable transaction ledger — each record captures the amount, type, status, and a related identifier, while the current balance is derived from the journal.
Every operation gets an idempotency key: a repeated request with the same key does not create a second record but returns the result of the first. This eliminates double debits when the connection drops, when the client did not receive a response and repeated the request.
Funds reservation and transaction reconciliation
A debit goes through two phases: first the amount is reserved, then it is confirmed or released based on the payment provider's response. The reservation appears in the balance as a separate line, so the user does not spend the reserved amount twice.
Background transaction reconciliation compares the ledger with the provider's statements on a schedule and flags discrepancies — stuck operations are closed automatically rather than through manual review.
The share of stuck payments drops from percentages to fractions, and recovery after a failure takes minutes, because the state is restored from the journal rather than from the service's memory.
What to choose under load
| Option | When it fits | Limitations |
|---|---|---|
| Transaction ledger + reserves | High frequency of debits, multiple providers | Requires discipline around idempotency keys |
| Direct balance modification | Simple scenarios without concurrent operations | Double debits on retries, manual reconciliation |
| Turnkey external payment service | Fast launch, minimal in-house logic | Weaker control over reconciliation and rollbacks |
We build the accounting scheme on a transactional core with an operations journal — this way the wallet state remains reproducible, and every transaction is traceable to its source.
The approach has been proven on payment systems at the level of PostgreSQL with integrity guarantees at the storage level.
Describe your accounting scheme and providers — we will come back with an estimate and an architecture plan.
Wallet App Development Stages: From Audit to Handover
Developing a mobile wallet app is first and foremost a project about money and trust, not about screens.
A mistake in the transaction model or in handling a repeated request costs more than all the rest of the code: the user sees funds debited twice, and support has to sort out the incident manually.
That is why the wallet development stages are built around the payment core, and the interface connects to logic that has already been verified.
Below is the route we follow through a project. Each stage ends with an artifact that can be checked, not a verbal "done."
- Audit of the current setup. We look at how transactions work now: where the balance is stored, who is the source of truth, which providers and banks are already connected, how refunds and cancellations are handled. The output is a flow map and a list of bottlenecks.
- Designing the transaction model. We lock down payment states (created, processing, confirmed, declined, refunded), idempotency rules, and the reconciliation procedure. This is the core: how the app behaves when the connection drops depends on it.
- Implementing the payment module. We connect acquiring, top-ups, withdrawals, and transfers between users, and set up webhooks and retries. Every scenario gets a clear error code instead of "something went wrong."
- Designing transactions and limits. We log every movement of funds, set limits, anti-fraud rules, and access roles for the admin panel. The transaction history must reconcile with the provider's data down to the penny.
- Testing payments against real scenarios. We run successful and failed cases: insufficient funds, provider timeout, double tap, refund, cancellation midway. Separately, we test on a weak connection and when the app restarts.
- Handover and documentation. We hand over the source code, flow diagrams, integration descriptions, deployment instructions, and a support checklist. The client's team can develop the product without us.
The six-stage scheme delivers a predictable result: the payment core is separated from the interface, and every change is verified in a test environment before reaching users. Describe your task — we will come back with an estimate and a stage-by-stage plan.
What is the difference between a prepaid wallet and a settlement account in an app?
A prepaid wallet and a settlement account in an app are two fundamentally different models of storing funds, and the entire logic of a mobile wallet app depends on the choice: how transactions are recorded, where the boundary lies between the user's balance and the money on the partner's side, and which operations are permissible at all.
In a prepaid wallet, the user first deposits funds into the issuer's account, and only then spends them from the balance.
The app operates not with money directly, but with an obligation: the balance is an entry in an internal ledger that the issuer is obligated to redeem upon a transaction.
This gives rise to strict constraints — limits on top-ups and remaining balance, a prohibition on transfers to third parties above an established threshold, and mandatory identification when levels are exceeded.
For the app, this means that every operation goes through reserving the amount, and the balance state must be synchronized with the issuer's ledger rather than treated as the source of truth.
A settlement account in an app works differently: the funds reside in the client's bank account, and the app is a channel for accessing it.
Here the balance is always reconciled with the banking core, operations are initiated through a payment gateway, and the limits and rules are dictated by the bank, not the product.
The app's logic becomes more complex: it must handle asynchronous confirmations, rollbacks when funds are insufficient, and statuses that arrive with a delay.
Refunds in a wallet are the most sensitive area. In the prepaid model, a refund is credited back to the wallet balance, and the app must correctly handle partial refunds, cancellations, and re-crediting without creating duplicate entries.
In the settlement account model, the refund goes to the bank account, and the app merely displays the status — but it must show the user exactly where the money will arrive and when.
The practical conclusion for architecture: mixing both models in a single product without a clear separation of ledgers is not acceptable — it leads to balance discrepancies and disputed transactions.
At the design stage, we establish who the issuer is, where the truth about the balance is stored, and how refunds are processed — and it is on this basis that we build the layer of operations and reconciliations.
Case study: how we eliminated double charges and stuck payments
The client came with a classic payment product pain: in the mobile wallet app, when the network dropped or the "Pay" button was pressed again, the transaction went to the bank twice, and some transfers got stuck in an intermediate status.
Incident triage was done manually via logs, support was drowning in tickets, and the user's balance diverged from the actual account state.
We started with an audit of the payment loop and found the root cause: the client initiated a charge but had no end-to-end operation identifier that would survive a connection drop and a resend.
Without it, any retry on the app or network side created a new transaction instead of continuing the existing one.
What we changed
We introduced an idempotent operation registry: every payment attempt gets a unique key that is generated on the device and stored locally until confirmation from the payment gateway.
Resending with the same key does not create a new operation but returns the current status of the one already started — double charging becomes impossible at the data model level.
We added a finite state machine of statuses with explicit transitions and timeouts: a "stuck" operation, once the waiting window expires, automatically goes to reconciliation with the bank instead of remaining in limbo. A background worker resolves such cases without human involvement.
Metrics before and after
| Metric | Before | After |
|---|---|---|
| Share of stuck operations | high, manual triage | isolated cases, auto-reconciliation |
| Time to manually triage an incident | tens of minutes per operation | minutes, exceptions only |
| Support tickets about payments | a steady stream | dropped severalfold |
| Double charges | recurred on retries | eliminated at the registry level |
We separately closed the observability gap: every operation got an end-to-end identifier in logs and tracing, so an incident is now triaged from a single line rather than a day's worth of exports. Support sees the payment status in real time instead of having to ask engineers.
Idempotency is not a nice-to-have but a baseline requirement for any payment application: without it, retries and an unstable network are guaranteed to produce discrepancies.
We design such loops so that correctness does not depend on the quality of connectivity on the user's side.
Compatibility, migration, and rollback: what to discuss before kickoff
Migrating a payment module is the riskiest part of a project: the core already holds balances, limits, and transaction history, and any desynchronization with it becomes instantly visible to users.
That is why, before kickoff, we lock down the exchange contract with the core, the data transfer scheme, and the point from which changes can be rolled back without losing already-processed transactions.
What if the current core does not support the required methods? Then compatibility is covered by an adapter on the service side: the application does not change the contract, and a layer brings the calls in line with what the core can do.
Such a layer isolates the modifications and requires no changes in the core's production environment.
How is wallet data transferred? Through staged reconciliation: first a shadow write to the new storage, then a comparison of checksums for balances and history, and only after they match — switching reads.
Rollback at this step means returning the pointer to the previous source, without deploying the old build.
What if the release turns out to be problematic? We maintain backward compatibility of formats and enablement flags: the new logic is disabled remotely, and the application continues to run on the previous contract. The user does not lose access to their balance even during a rollback.
How is access security ensured during handover?
Access is granted on the principle of least privilege: separate accounts for each environment, keys with a limited lifetime, and logging of all calls to the core. When work is completed, access is revoked and keys are rotated — this is recorded in a report.
The customer receives:
- a diagram of the application's integration with the core and a description of the exchange contract;
- a data migration regulation with reconciliation points and switchover criteria;
- a change rollback procedure with a step-by-step scenario;
- an access matrix and a key rotation policy;
- wallet documentation: a description of modules, scenarios, and edge cases;
- a set of checks for acceptance — what and how is tested before rollout;
- a log of known limitations and a plan to close them.
Describe your task — we will get back to you with an estimate and a plan: we will work through the integration with the current core, the scope of data transfer, and the rollback procedure.