Drive the console without breaking the books.

Signing in

When AUTH_TOKEN is set, /ops redirects you to /ops/login. Paste the operator token and submit — the server hands back an HttpOnly session cookie good for 12 hours and drops you on the overview. A wrong token is refused in place with an inline invalid token message and no session is created — there's no way to half-authenticate. (Where Google sign-in is configured, the same page offers Continue with Google; the allow-list is re-checked on every request.)

Reading the overview

The landing page is read-only — a live pulse of the core. Seven things to read, in the order they matter:

• Formance / ledger health — the chip that says the adapter answered. Anything but healthy and stop: commands will 500.
• TX posted / TX failed — cumulative postings. Failed climbing is your first smell of trouble.
• Outbox pending + oldest pending (s) — events awaiting the relay worker. In dev no relay runs, so a non-zero, ageing pending count is expected, not an incident.
• Recon drift + template mismatch — both should read 0. These are the headline numbers from the four gates (chapter 03).

Beneath the counters is the recent-ledger-transactions list — every posting with its time, type, status, merchant, amount and reference. This is the fastest place to find a transaction id for a reversal.

Create before you fund

The single most common first-time stumble: a pay-in for a merchant that has no wallet yet fails with wallet <merchant>/<ccy> not found. Despite the name, ensureWallet does not create — it asserts the wallet exists and rejects if it doesn't. So on Wallets, use the create-wallet form (merchant id + currency) first, then fund. One wallet per currency: the same merchant in NGN and USD is two rows.

The four-part balance

Open a merchant and the snapshot reads live from the ledger — balances are derived, never stored:

• Available — what the merchant can actually spend right now.
• Ledger — the gross book balance before holds are subtracted.
• Locked — funds tied up in reserved payout holds (amount + fee + VAT).
• Reserve — rolling-reserve risk hold, separate from payout locks.

Fund a wallet and available reflects the net credit immediately (a 50,000 pay-in with a 500 fee lands 50,000 to the merchant, books the fee to revenue separately — the fee does not come out of the merchant's number).

The idempotency key, and when it rotates

Every money form carries a hidden, auto-generated idempotency key. Watch it in the pay-in form: submit successfully and the key rotates to a fresh value, so your next submission is a new command. But after a failed response the key is kept on purpose — retrying a failure is a replay of that same attempt, never a second operation. This is by design; don't "fix" it.

Duplicate collections are deduped at the source

Pay-ins also dedupe on (provider, providerReference) independent of the idempotency key. Submit a second pay-in with the same provider reference (even with a brand-new key) and it is refused with provider event already processed. The wallet shows exactly one credit, never two, and Controls → provider events lists that reference once. This is the defence against a provider firing the same webhook twice.

The overdraft guard is the ledger, not a check

Transfer more than a wallet holds and the ledger rejects it atomically: merchants:<m>:<ccy> has insufficient NGN/2 balance. The source is unchanged, the destination is unchanged, and neither statement shows a partial posting. There is no check-then-act window to lose a race in — the Numscript send either moves the whole amount or nothing. If you ever see one leg post without the other, that is a critical incident; in normal operation it cannot happen.

The console never navigates away to report a problem — results swap in place via HX-Trigger. What renders tells you which layer spoke:

Worked examples from the console

• Empty amount → Amount is required (inline). Negative amount → Amount must be a positive decimal (inline).
• Empty correction reason → Reason is required (inline) — reason is mandatory on every correction.
• Currency ZZZ → unsupported currency 'ZZZ': add it to CURRENCY_SCALES… (red card). Unknown currencies are fail-closed — never guessed, never given a default scale.
• Over-balance transfer / unfunded offramp → … has insufficient … balance (red card). Expected, not a bug.

A payout starts as a reserve on Operations: it moves amount + fee + VAT out of available into locked and creates a hold in status reserved, which appears on Payouts with its reference and amounts. A PAYOUT_SAGA_REQUESTED event lands in the outbox (pending in dev — no relay). From there the hold reaches exactly one terminal state:

Acting on a hold

On Payouts, the ACT button on a row opens the manual hold actions and prefills the Settle and Release forms with that hold's reference, merchant and amounts — you rarely type anything. Settle (provider confirmed payment) drains locked to the bank and books fee/VAT; locked drops to zero. Release (provider failed) returns the full reserved amount to available. Dead-letter parks the hold in manual_review with a reason; settle and release remain available from there, so you resolve it the same way.

Settle XOR release — proven

Once a hold is settled, attempting to release it is refused (holds:<m>:<ccy> has insufficient … balance — the locked funds are already gone). A second settle has no balance effect. A hold reaches one terminal state and stays there. The status-filter tabs (all / reserved / settled / released / manual_review) and their counts stay consistent as you work.

Corrections — the everyday adjustment

Operations → Ledger correction posts a credit or debit with a mandatory reason (chargebacks, ops adjustments). The amount moves the merchant's balance immediately and the statement entry carries the correction reference. The optional effectiveAt field posts bi-temporally — back-date it to the day the event really occurred and the console accepts it. A delivered-then-disputed collection is a debit correction with reason chargeback …; this is the right tool the vast majority of the time.

Reversals — unwind a posting by id

Operations → Reverse transaction takes a walletflow transaction id (grab it from the wallet statement or the overview's recent-transactions list) and unwinds that posting. A wrong id is refused cleanly with ledger transaction not found — it will not guess.

Replay safety

Both doors are idempotent. A correction re-submitted with the same key replays; a completed reversal is guarded against running twice. The balance changes exactly once — a double-reversal cannot happen by re-clicking.

Reconciliation — the four gates

Each panel on Recon runs its gate when the page loads (give the lazy-loaded panels a second; none should spin forever):

• Gate 1 · statement drift — read-model vs ledger. Expect zero.
• Gate 2 · trial balance — must foot per currency.
• Gate 3 · reserved holds vs hold accounts — every reserved hold backed 1:1 by ledger hold balances.
• Gate 4 · COA / GL / template coverage — no mapping gaps.

When wallet drift shows, click Rebuild statement read model first — projection lag is the usual cause and the rebuild is idempotent. Only if drift survives a rebuild do you investigate a real discrepancy. Beneath the gates, ALM views show obligations against balances.

Ledger & Controls

Ledger browses the chart of accounts, the event→GL mappings and the 18 Numscript templates, with rebuild buttons and a CSV export for Finance — the template count should match the bundled set. Controls (admin) is your freeze switch and audit window: set a core_wallet_enabled feature flag for a merchant / currency / provider scope to block new exposure (with CORE_WALLET_FLAG_MODE=fail_closed, only enabled scopes transact); watch the outbox dispatch with attempts and errors; and audit the provider-event log that blocks webhook replays. Saga completions still record by default — a true hard freeze needs CORE_WALLET_COMPLETION_GATING=gate (an env change, so a restart).

Command fields & what success looks like

Looks broken — isn't