Every way money moves in MyNEX, one page

Summary matrix — operation × system account touched

Every row below ends in exactly one thing: a call to ledger.Post (zero or more legs against system accounts) plus a matching ledger.ApplyToWallet, in the same DB transaction — except the two card-hold rows, which touch Wallet.LockedBalance only and never call ledger.Post at all (see Ledger → card-hold design and Reconciliation → card holds as the deliberate exception).

Wallet top-up — five methods, one settlement engine

All five top-up routes share payment-service.SettlementEngine — see the full state-machine sequence at Data Flows → Top-up settlement. This section is about the ledger shape, not the state machine. The Kind is ledger.KindTopup in every case — only the system-account counterparty changes by method, matching the settlement's SystemAccount field set at the call site in wallet-service.Service.

Bank / MVR top-up

Reference: Transaction.Reference (auto "TXN-<uuid>" via BeforeCreate), reused as the ledger transaction reference. Failure path: a failed authorize or a give-up after PAYMENTS_MAX_SETTLEMENT_ATTEMPTS (20) polls marks the transaction/settlement failed — no ledger entries ever existed, so there is nothing to reverse.

Card top-up

Identical shape to bank/MVR — only the counterparty account changes. Sandbox provider settles deterministically after PAYMENTS_SANDBOX_SETTLE_DELAY (5s); a real Stripe integration completes via the signed webhook instead of the sweeper poll.

Crypto top-up

Apple Pay top-up

Google Pay top-up

Apple Pay and Google Pay both route through card_settlement, not a dedicated digital-wallet account — the platform treats a tokenized card charge as a card settlement regardless of the wallet UI it came through.

Withdrawal

Unlike top-up, the debit is posted synchronously and up front, before any "bank payout" happens. The payout itself is honestly not real: go s.processWithdrawal(...) is a fire-and-forget goroutine that does exactly this and nothing else:

func (s *Service) processWithdrawal(ctx context.Context, transaction *models.Transaction) {
    time.Sleep(5 * time.Second)
    transaction.Status = "completed"
    now := time.Now()
    transaction.ProcessedAt = &now
    s.repo.UpdateTransaction(ctx, transaction)
}

No real bank rail is called. This is a known, tracked simplification (Security → Known limitations) — the ledger debit is real money leaving the user's spendable balance, but the "payout" is a timer.

P2P transfer

Sender debited amount + fee in one leg. Failure: insufficient balance trips ledger.ErrOverdraft → INSUFFICIENT_BALANCE, and the entire request rolls back — no partial state, nothing to compensate.

QR payment

This example shows the 1 MVR floor kicking in: 0.5% of 50.00 is 0.25, below the floor, so the fee is 1.00. The only difference from a plain P2P transfer is Transaction.PaymentMethod gets overwritten to "qr_code" after the underlying transfer completes.

Bill payment

Fee is always decimal.Zero on the transaction row. The ledger only posts if the gateway responds "completed" — any other gateway status (e.g. "requires_action") saves the transaction row with no ledger posting at all. There is no partial-debit state to clean up.

NFC payment

FX conversion

Four legs, two independent zero-sum checks in one Post call — this is what a cross-currency operation actually is under the ledger's per-currency invariant. fx_spread's net position across both legs is the platform's captured margin. Failure: expired/already-consumed quote → QUOTE_EXPIRED; insufficient balance → ErrOverdraft — both reject before any posting.

NAQD mint / burn / on-chain withdraw

All three are asynchronous — the API only creates a NAQDOperation row; a background worker posts the ledger and calls the chain. Full lifecycle detail, oracle fallback, and economics: NAQD Minting & Reserves.

Mint

Burn

naqd_reserve's fiat leg is debited the gross amount (102.88); the user receives the net amount (102.37) after the 0.51 fee, which lands in fees — five legs in one posting.

On-chain withdrawal (self-custody)

Only two legs, NAQD-only — no fiat ever moves, since the coin already existed as a custodial balance; this operation only changes who controls it on-chain. Failure (all three NAQD kinds): the worker's reverseAndFail loads the original LedgerTransaction, negates every entry, and reposts it under KindAdjustment with reference <original-ref>-REVERSAL, then publishes system.alert. See NAQD Minting → mint lifecycle for the full quoted code.

Card lifecycle

The defining design choice for cards: a hold only ever moves Wallet.LockedBalance. Nothing is posted to the ledger until the hold actually clears. See Ledger → the card-hold design and Reconciliation → card holds as the deliberate exception for why this is correct, not a shortcut.

Authorization hold

Clearing / capture

Alongside the ledger posting: ApplyToWallet(−42.17), then AdjustLockedBalance(−80.00) — the full original hold, not just the 42.17 captured — releases in the same transaction.

Reversal (hold released, never captured)

Refund (after capture)

No fee logic surfaced anywhere in card-service for any of the four card operations — none charge a platform fee in the current implementation.

Partner rail — Touch 'n Go eWallet reload

Fee = 2.00 + 1.5%×500.00 = 9.50. The rail's own currency (MYR) never appears in the ledger — only what the user actually paid with. Execution then calls impl.Execute(...) (TnG sandbox returns a deterministic partnerRef); completion is simulated after rail.ETASeconds (30s default) via a background goroutine, with deterministic (FNV-hashed, not math/rand) simulated failure.

Partner refund

The exact negation of the execute posting — the full amount including the fee is refunded, since no service was actually rendered. Idempotent: a second refund attempt on an operation no longer processing is a no-op.

Admin wallet adjustment

A negative (debit) adjustment posts the mirror image — user account debited, external_funding credited — and hits the same ErrOverdraft guard as any other posting if it would overdraw the wallet; the whole approval transaction (ledger + wallet + audit log row) rolls back and the adjustment stays pending. Reject is a pure status transition (pending → rejected) with no ledger interaction at all.

Recurring payment execution

Failure: markRecurringFailure increments ConsecutiveFailures and advances NextPaymentDate regardless (so a permanently-broken mandate doesn't hot-loop the sweeper), auto-disabling the mandate once RECURRING_MAX_CONSECUTIVE_FAILURES (default 3) is reached. No events.Publish anywhere in this path.