Design a Digital Wallet System (like Paytm/Google Pay)

• Double-entry ledger : every operation writes two matching entries (debit + credit) so the sum is always zero.
• Idempotency : each operation carries a unique key; replays return the same result without moving money twice.
• Optimistic locking : balance updates succeed only if the row version is unchanged since read, preventing lost updates.
• Settlement : moving funds between the wallet system and partner banks.
• Reconciliation : comparing the wallet ledger against external gateway records to detect and repair mismatches.

How does double-entry balance management work?

Every operation produces two matching ledger entries. A top-up credits the user's wallet and debits a funding source. A payment debits the payer and credits the payee. The signed sum across both entries is always zero. This is the same accounting principle used by National Bank of India's core banking system.

package com.bank.wallet;

import java.math.BigDecimal;

public class WalletLedger {
    public void topUp(String walletId, BigDecimal amount, String fundingSource) {
        ledger.append(new Entry(fundingSource, amount.negate())); // debit source
        ledger.append(new Entry(walletId, amount));               // credit wallet
    }
}

How does optimistic locking protect the balance?

Each wallet row has a version column. A debit succeeds only if the version is unchanged since the read. If two concurrent requests try to debit the same wallet, only one wins. The loser gets zero rows updated and must retry with the fresh version.

package com.bank.wallet;

import java.math.BigDecimal;

public class OptimisticLockingDebit {
    public boolean debit(String walletId, BigDecimal amount, long expectedVersion) {
        int rows = jdbc.update(
            "UPDATE wallets SET balance = balance - ?, version = version + 1 " +
            "WHERE id = ? AND version = ? AND balance >= ?",
            amount, walletId, expectedVersion, amount);
        return rows == 1;
    }
}

How does idempotency work?

Each operation carries a client-generated key. The server records outcomes by key, so replays return the same result without moving money twice. If Rajesh's phone retries a top-up because the network timed out, the wallet returns the original result.

package com.bank.wallet;

import java.math.BigDecimal;

public class IdempotentWalletService {
    public WalletResult topUp(String idemKey, String walletId, BigDecimal amount) {
        WalletResult prior = idempotencyStore.get(idemKey);
        if (prior != null) return prior;  // safe replay
        WalletResult result = executeTopUp(walletId, amount);
        idempotencyStore.put(idemKey, result);
        return result;
    }
}

How do P2P transfers work atomically?

Debit sender and credit receiver in a single database transaction. If either leg fails, the whole transfer rolls back. The idempotency key prevents duplicate transfers on retry.

package com.bank.wallet;

import java.math.BigDecimal;
import org.springframework.transaction.annotation.Transactional;

public class P2PTransferService {
    @Transactional
    public void transfer(String from, String to, BigDecimal amount, String idemKey) {
        if (idempotency.seen(idemKey)) return;
        ledger.post(from, to, amount);
        walletRepo.debit(from, amount);
        walletRepo.credit(to, amount);
        idempotency.record(idemKey);
    }
}

How do daily and monthly limits work?

Limits are checked before each spend operation. An over-limit operation is blocked before any money moves. This satisfies RBI regulations and limits the damage from a compromised account. The limit check queries the sum of recent transactions within the window.

package com.bank.wallet;

import java.math.BigDecimal;

public class LimitChecker {
    private static final BigDecimal DAILY_LIMIT = new BigDecimal("100000.00");

    public void checkDailyLimit(String walletId, BigDecimal amount) {
        BigDecimal spentToday = ledger.sumDebitsToday(walletId);
        if (spentToday.add(amount).compareTo(DAILY_LIMIT) > 0)
            throw new DailyLimitExceededException(walletId, DAILY_LIMIT);
    }
}

How does fraud detection work?

The system scores each transaction on velocity (how many transactions in the last hour), amount (unusually large), and device signals (new device, new location). Suspicious transactions are blocked or challenged with an OTP. Rajesh transferring 50,000 rupees from a new device at 3 AM triggers a challenge.

How does refund work?

A refund is a new pair of ledger entries: credit the original payer, debit the merchant. Never edit the original payment entries. Both the payment and the refund are visible in the ledger, linked by a reference id, preserving the full audit trail.

How does reconciliation handle partial failures?

If a top-up succeeds at the gateway but the local write fails, the reconciliation job detects the mismatch by comparing the gateway's settlement file against the wallet ledger. It creates correcting entries and alerts the operations team. No money is ever silently lost or gained.

What should a senior engineer know?

Designing idempotency, optimistic locking, atomic transfers, and reconciliation together is what makes a wallet trustworthy enough to hold real money. A senior engineer also designs for multi-currency support, plans the settlement cycle with partner banks, and monitors reconciliation mismatches as a key operational health metric.