How to build an e-wallet app: ledger first, license early, loop always

The e-wallet is Southeast Asia's signature fintech product: hundreds of millions of users who skipped cards entirely and went from cash to QR codes, an entire merchant economy running on scan-to-pay, and a graveyard of hundreds of licensed wallets that built the same app and never found a reason for anyone to open it twice. Both facts matter to anyone planning a build. The technology is well understood and honestly not exotic; the difference between MoMo and the wallet nobody remembers is almost never in the code.

This guide covers both halves honestly: the build, the stored-value model and the license behind it, the ledger that deserves most of the engineering respect, the top-up and payment rails, the security and KYC floor, the merchant side that doubles the scope, with a phased plan and offshore costs, and the strategy, the daily-use loop and distribution reality that should be settled before the first sprint, because it changes what you build first.

It completes a fintech cluster: the mobile banking build guide covers the regulated-account sibling wallets often graduate into, and the MoMo and ZaloPay case studies show, in production detail, where wallet strategies in Vietnam actually led.

The stored-value model and the license behind it

An e-wallet's legal skeleton is stored value: users hand you money, you record a liability to them on your ledger, and the actual cash sits in a safeguarded trust account at a bank, segregated from your operating funds and reconciled against the sum of user balances. This is what the e-money license regulates: capital requirements, safeguarding rules, transaction and balance limits, KYC obligations, and reporting. It is deliberately lighter than a banking license, no lending, no interest on balances in most regimes, which is exactly why wallets ship in months where banks take years, and why the wallet is the standard first move for Southeast Asian fintechs.

The license path is the first fork in the plan. Holding your own e-money license gives you the economics and the roadmap freedom, at the price of capital requirements, a licensing process measured in quarters, and a permanent compliance function; this is the path for funded companies whose core business is the wallet. Partnering with a licensed institution, riding a bank's or an existing e-money holder's license through a commercial agreement, compresses time to market and defers the capital burden, at the price of revenue share, roadmap veto points, and a partner in every regulator conversation. The pattern across the region: partner to prove the loop, license once volume justifies the capital.

The regulatory geography matters more than in most software because the license does not travel. Vietnam, Indonesia, the Philippines and Thailand each run their own e-money regimes with different limits, KYC tiers and safeguarding rules, and a wallet expanding across them is running parallel licensing projects, one reason regional wallet consolidation happened through acquisition rather than expansion. For a first build, pick one market, read its e-money circular before the architecture review, and encode its tier limits into the ledger from day one, because retrofitting per-tier balance caps into a live ledger is miserable, auditable work.

License path decides the project shape

Dimension	Own e-money license	Licensed partner
Time to market	Quarters of licensing before launch	Months; partner certification only
Capital	Regulatory minimum locked up	Deferred; partner carries it
Economics	Full margin on float and fees	Revenue share, per-transaction costs
Roadmap	Yours, inside the regulations	Partner approval on regulated features
Compliance	Your function, built from scratch	Shared, but you still own your conduct
The pattern	License once volume justifies it	Partner first to prove the loop

Both paths ship the same app. They ship different companies.

The ledger is the product

Every screen in a wallet is a view over one system: the ledger that records who holds what. Build it double-entry from the first commit: every movement is a balanced transaction, a top-up debits the trust-account mirror and credits the user, a payment debits the user and credits the merchant net of fees, with fee lines as explicit entries rather than arithmetic scattered through service code. Double-entry is not accounting pedantry; it is the property that makes the system provable, the books balance or they do not, and the shape every auditor, partner bank and regulator will ask to see.

Three engineering properties are non-negotiable because every incident in wallet history traces to missing one. Append-only: entries are never updated or deleted, corrections are new reversing entries, so the ledger is also the audit trail. Idempotent: every mutation carries a client-generated key, and a retried top-up callback or a double-tapped payment button executes once, because networks retry and users double-tap as a law of nature. And serialized per account: two simultaneous spends against one balance must linearize, through row locking or single-writer account streams, because the alternative is negative balances discovered at reconciliation, and explaining those to a regulator is a career event.

Reconciliation is the ledger's external proof and runs on two seams. Inward: the trust account statement against the ledger's trust mirror, daily at minimum, because safeguarding rules assume you can demonstrate the match on demand. Outward: every rail partner's settlement file, bank top-ups, card acquirer, QR switch, biller aggregator, against the ledger's view of the same flows, with every mismatch in an exception queue owned by a named human. Wallets that treat reconciliation as a monthly finance chore run blind between checks; wallets that treat it as a daily engineering output with alarms catch their bugs, and their fraud, in hours.

One architectural consequence deserves emphasis because it saves a future migration: build balance reads and statement queries on read models projected from the ledger stream, not on the write path. Wallet read traffic, balance checks before every payment, transaction histories scrolled daily, outweighs writes enormously, and read models keep the hot ledger tables small and the queries instant. This is the same read-model discipline as the banking middleware, applied one layer down, and it is also the graduation insurance: a wallet ledger built this way survives the audit when the company later reaches for regulated accounts.

Ledger discipline

Do this

• Double-entry with explicit fee linesEvery movement balances. Fees are entries, not arithmetic hidden in services.
• Append-only with reversing correctionsThe ledger is the audit trail. History is never rewritten, only extended.
• Idempotency keys on every mutationRetried callbacks and double taps execute once. This is table stakes, not polish.
• Daily reconciliation with a worked queueTrust account and every rail partner, matched daily, mismatches owned by name.

Not this

• Balances as a mutable columnAn update statement is not a ledger. The first dispute proves it.
• Fees computed in application codeUnbalanced books that no one can explain at audit, guaranteed.
• Concurrent spends left to chanceNegative balances at reconciliation, and a very hard regulator meeting.
• Reconciliation as a monthly choreA month of blindness between checks is where fraud and bugs compound.

The properties that make a stored-value ledger provable rather than merely plausible.

The rails: money in, money around, money out

Money-in is the growth constraint, and top-up friction is the most reliable funnel killer in the category. The baseline is bank top-up over the local instant rail, ideally free to the user and instant in the balance, plus card top-up for the card-holding minority, plus, in cash-heavy markets, an agent and convenience-store network, which is a business development project as much as an integration. Each rail arrives as an asynchronous callback that must be verified, matched to a pending intent, and posted idempotently to the ledger; the engineering is exactly the payment-saga discipline of any money product, and the product bar is one screen, a few seconds, and a balance that updates before the user's doubt does.

Money-around is where the wallet earns its place on the home screen. Peer transfers by phone number with the contact book as the interface, instant and free, because peer transfer is the viral loop, not a revenue line. QR payments at merchants, both wallet-scans-merchant and merchant-scans-wallet, and in most Asian markets interoperable with the national QR standard, VietQR, QRIS, PromptPay and their siblings, which converts every existing acceptance point into your acceptance point and is now table stakes. Bill pay and telco top-up through a biller aggregator, unglamorous and the single stickiest feature in most wallets' retention data. Every flow ends in an unambiguous terminal state with an instant push notification, the same discipline as banking, because ambiguity is where support queues are born.

Money-out is where trust is proven: withdrawals back to bank accounts, priced gently and delivered reliably, because the moment a user cannot get money out is the moment the wallet becomes a story on social media. Operationally, money-out is also the fraud choke point, the place where stolen balances try to leave, so it carries the tightest velocity limits, the step-up authentication, and the risk scoring described in the next section. The design tension is real: security wants friction at withdrawal, growth wants none anywhere, and the resolution is risk-based, invisible checks for the normal case, ceremony only when the signals disagree.

The floor: KYC tiers, device trust, and the fraud queue

Wallet KYC is tiered by design, and the tiers are a product feature as much as a compliance one. The typical regime: a minimal tier opened with a phone number and basic identity, carrying tight balance and transaction caps; a verified tier unlocked by document capture and a liveness-checked selfie match, carrying the useful limits; and sometimes a premium tier with enhanced diligence for the heaviest users. The product craft is treating tier upgrades as contextual moments, prompt the upgrade when the user first hits a cap, mid-intent, with the benefit explicit, rather than demanding maximum KYC at signup and paying for it in abandoned installs. The vendor-versus-funnel split is the same as banking: buy the verification, own every screen around it.

Device and session security follows the fintech baseline with wallet-specific emphasis. Device binding at registration, a key in secure hardware, so a credential thief without the device still cannot transact; biometric or PIN on open, and a transaction PIN ceremony on money movement, scaled by amount; SIM-swap awareness in markets where the phone number is the identity, meaning re-verification when the device or SIM changes; and the runtime protections, root detection, overlay defense, screen-capture suppression on sensitive views, that the banking build guide details, all of which apply unchanged.

Fraud in wallets concentrates in three patterns and the defense is a worked queue, not a model alone. Account takeover, phished credentials cashing out through withdrawals or peer transfers to mule accounts, countered by device binding, velocity limits and risk-scored step-up at money-out. Social-engineering payments, victims persuaded to send, countered by warnings on first-time recipients, cooling periods on unusual amounts, and a reporting path that can freeze mule accounts fast. And promotion abuse, fake accounts farming top-up bonuses and referral rewards, countered by device fingerprinting and KYC-tier gates on incentives, and worth engineering before the first cashback campaign rather than after it burns six figures in a weekend. Every rule feeds a case queue with service levels and resolution codes tuning the rules, the identical rhythm to banking, fleet fuel, and every other exception-driven system this site documents.

The risk build, in the order it earns its keep

1. 1

   Device binding and transaction PINBefore launch

   Kills pure credential theft on day one. The cheapest, highest-yield control in the stack.

2. 2

   Velocity limits by KYC tierBefore launch

   Caps the blast radius of anything that gets through. Encoded in the ledger, not the UI.

3. 3

   Risk-scored step-up at money-outBefore launch

   Friction only when signals disagree. Withdrawals are where stolen value tries to leave.

4. 4

   First-recipient warnings and cooling periodsFirst quarter

   The social-engineering counter. Saves users from themselves at the moment it matters.

5. 5

   Promotion-abuse fingerprintingBefore growth spend

   Before the first cashback campaign. Bonus farms assemble faster than dashboards notice.

6. 6

   The worked queue with resolution codesLaunch, permanently

   Humans on service levels, dispositions tuning rules. The system that makes the rest improve.

Each layer pays for itself against a specific, dated pattern of loss.

The merchant half nobody budgets

Every wallet plan begins as a consumer app and every successful wallet becomes a two-sided product, because the revenue chart earlier in this guide is blunt: merchant payments are the engine. The merchant side is its own build: onboarding with business KYC (lighter for market stalls, heavier for chains), a merchant app or dashboard showing payments in real time, because the stall owner's trust depends on the phone buzzing before the customer leaves, settlement on a schedule with fees transparently lined out, refunds and disputes with a workflow rather than a hotline, and, for larger merchants, APIs and plugins for online acceptance. Budget it as roughly forty percent of the total build, because that is what it historically consumes.

The settlement design has a subtlety worth stating: merchant balances are ledger accounts like any other, credited net of fees at payment time or at batch, with payouts to bank accounts as ordinary money-out flows under the same reconciliation regime. Holding merchant funds even briefly makes you a counterparty risk in their cash flow, so payout reliability is a trust product for the acceptance side exactly as withdrawals are for consumers, and the operational alarms on delayed settlement batches should wake someone up. Disputes deserve a state machine from day one, claim, evidence, resolution, ledger adjustment via reversing entries, because the ad-hoc version becomes a spreadsheet that fails its first audit.

The field reality: merchant acquisition in QR-first markets is boots and stickers, agents onboarding stalls one by one, and the interoperable-QR era has restructured the economics of it. Where any wallet can pay at the national-standard code, the acquiring wallet earns its fee by being the merchant's operating tool, the dashboard, the settlement, the credit line against payment history, rather than by owning the code on the counter. That reframes the merchant product from a network land grab into a services business, and it is a better business, but only for teams that actually build the services.

Consumer build versus merchant build

	Consumer side	Merchant side
Onboarding	Tiered personal KYC, contextual upgrades	Business KYC, tiered by merchant size
Core surface	App: pay, transfer, top up, bills	Dashboard and app: live payments, settlement
Money movement	Top-ups in, QR and transfers around	Net settlement out, refunds as reversals
Risk	Takeover, social engineering, promo abuse	Collusion, fake sales, settlement fraud
Support load	Payment states, KYC, account access	Disputes, settlement timing, reconciliation
Build share	Roughly sixty percent	Roughly forty percent, reliably underestimated

Two products, one ledger. The merchant column is the one first budgets forget.

The build plan and what it costs

Phase one, the first two to three months, is the ledger and the license path in parallel: the double-entry core with its idempotency and serialization guarantees, the read models, the reconciliation harness with the trust-account mirror, and, on the business track, the partner agreement signed or the license application moving, plus the KYC vendor integrated end to end. The exit test mirrors banking's: a test user passes tiered KYC, tops up from a real bank sandbox, and the ledger, the read model and the reconciliation report all agree about it.

Phase two, months three to six, builds both halves of the product in vertical slices: peer transfers with the contact-book UX, interoperable QR payment with the national switch certification (a scheduled external dependency, start the paperwork in phase one), bill pay through the aggregator, withdrawals with the risk-scored step-up, and the merchant dashboard with settlement and refunds. The risk stack from the security section lands here as each money-out and incentive surface arrives, and the fraud queue goes live with staffed rotations before any growth spend, not after.

Phase three is hardening and the seeded launch: load tests against the read models at concert-ticket concurrency, chaos drills on rail callbacks (the top-up that succeeds at the bank and times out at your API is a certainty, not a scenario), the reconciliation dry run for the regulator or partner, penetration testing with time to fix, and store review. Then launch into the daily-use loop the strategy section demands: a city, a corridor, an anchor merchant network or biller set where the wallet is immediately useful, expanding by cohort as the fraud and support queues prove workable, exactly the cohort discipline of a banking launch.

The budget, offshore: roughly 90,000 to 250,000 dollars to first launch. The bottom is a partner-license build, consumer app plus a lean merchant dashboard, one market, leaning on the national QR switch and a biller aggregator; the top adds an own-license compliance build-out, a full merchant product with APIs, agent tooling for cash networks, and the deeper risk stack. Steady state after launch: a product and engineering group of six to ten, one to three risk and support operators scaling with volume, KYC per-verification fees coupling to growth, and switch, aggregator and infrastructure costs forming a five-figure monthly floor, the same honest arithmetic as banking, one license class lighter.

A seven-month wallet build, phase by phase

1. Ledger and licenseMonths one to three

   Double-entry core, reconciliation harness, KYC vendor, partner or license track

   Done when Sandbox top-up posts, reconciles, and survives a duplicate callback

2. Both halvesMonths three to six

   Transfers, interoperable QR, bills, withdrawals, merchant dashboard, risk stack

   Done when Full consumer and merchant loop on staging with fraud queue staffed

3. HardeningMonth six

   Load, chaos on callbacks, reconciliation dry run, pen test, store review

   Done when Drills pass; regulator or partner sign-off on the evidence pack

4. Seeded launchMonth seven

   One corridor, anchor merchants and billers live, cohort ramp on queue health

   Done when Daily-use loop measurably running: repeat usage, not installs

Partner-license path shown; an own-license path adds quarters of regulatory lead time in parallel, not in series.

The planning numbers

$90k to $250k Build to first launch License path and merchant scope set the point in the range

5 to 9 months To seeded launch QR switch certification and license track are the external clocks

~40% Of the build is the merchant side Dashboard, settlement, disputes; the half first budgets forget

6 to 10 people Steady-state product and engineering Plus risk and support operators scaling with volume

Illustrative figures for an offshore e-wallet build on the partner-license path.

The loop that decides everything

The uncomfortable statistic behind this category: most licensed wallets that launched in Southeast Asia over the past decade are functionally dead, and almost none died of engineering. They died because nothing brought users back on Tuesday. The winners are monotonously alike in this one respect: each paired the app with a loop the user runs anyway, MoMo with bills, top-ups and an enormous merchant push, ZaloPay with the Zalo messaging graph, the ride-hailing wallets with the daily commute, and used that loop to make the balance worth keeping loaded. A wallet without a loop is a balance with no reason to exist, and users correctly refuse to fund it.

For a new entrant the loop question is answerable before any code: what does your user do weekly that this wallet makes cheaper, faster or possible, and what anchor, an employer disbursing salaries, a transit system, a market's stall network, a platform you already operate, gives distribution without buying every install. The strongest current answers are wallets attached to businesses that already have the audience: the platform adding stored value to its checkout, the employer channel disbursing wages into a wallet with bill pay attached, the vertical wallet for a community whose payments the big players serve badly. Standalone consumer wallets funded by cashback are, at this point, a well-documented way to convert venture money into merchant subsidies.

This is also the honest frame for the build-versus-wait decision. If the loop and the anchor exist, the build in this guide is a well-marked road: ledger first, partner license, interoperable QR, both halves of the product, seeded launch, and the banking graduation later if the economics call for it. If they do not exist, the missing work is business development, not software, and the kindest thing a technical partner can tell you is to spend the first budget on the anchor rather than the app.

Frequently asked questions

When the wallet needs a ledger built to audit grade, AgileTech is a top software house in Hanoi with payment and wallet systems running in production.