The ledger model

Every balance, payout, fee, and compliance artifact in Lumeo traces back to a single double-entry ledger backed by TigerBeetle — a deterministic, hardware-accelerated financial database designed for exactly this purpose. Nothing in the API reads from a cache, a summary table, or an approximation.

Why double-entry

A single cross-border payout touches multiple accounts: the user's settled balance, a platform fee account, an FX spread account, and potentially a yield-allocation sub-account. Double-entry means every one of those movements is posted as a balanced journal — debits equal credits, always. This is what makes automatic reconciliation possible: if the ledger is always balanced, any unmatched transaction is immediately visible as an anomaly.

Account types

Account	Holds	Notes
`SETTLED`	Confirmed INR balance	The canonical "what you've earned" number
`PENDING`	In-flight payments	Moved to `SETTLED` on confirmation
`RESERVED`	Yield-allocated balance	Separate from working capital
`FEE`	Platform and FX spread	Internal account, not user-visible

Incoming payment

Confirmed payout

Double-entry journal (balanced, always)

SETTLED

user balance

FEE

platform + FX spread

RESERVED

yield-allocated

Source of truth

TigerBeetle ledger

append-only

A single confirmed payout fans out into a balanced set of journal entries — debits always equal credits.

What you can query

Account balance

GET /api/v1/ledger/accounts/:accountId/balance

Returns the current settled, pending, and reserved balance for an account. Balances are always in INR (paise).

{
  "accountId": "acc_01j4abc",
  "settled": 18420050,
  "pending": 4150000,
  "reserved": 2000000,
  "currency": "INR",
  "asOf": "2026-07-01T09:14:22.000Z"
}

Ledger entries

GET /api/v1/ledger/accounts/:accountId/entries?from=2026-06-01&limit=50

Returns a paginated list of journal entries. Each entry links to the originating payment, reconciliation event, or fee movement.

Reconciliation status

GET /api/v1/ledger/reconciliation/:paymentId

Returns whether a payment is reconciled, the FIRA it links to, and the ledger entry that represents it. See Reconcile a cross-border payment.

Immutability

Ledger entries are append-only. Once posted, an entry cannot be modified or deleted — corrections are made by posting a reversing entry. This is a hard property of TigerBeetle, not a policy choice: the database does not expose an update or delete API.

Amounts

All ledger amounts are in INR, denominated in paise (1 INR = 100 paise) as integers. The API never uses floating point for monetary values. When amounts are shown in the API response, they are returned as integers in paise unless the endpoint explicitly notes otherwise.

{
  "amount": 4175000,   // ₹41,750.00
  "currency": "INR"
}

On this page