Ledger Service
Purpose
Authoritative source of financial truth. All monetary movements recorded as immutable double-entry transactions.
Responsibilities
- Double-entry transaction posting
- Debit/credit entry creation
- Balance calculation
- Transaction immutability
- Reversal via compensating entries
Non-Responsibilities
- Payment orchestration (Payment Service)
- Account lifecycle (Account Service)
- Fraud decisions
APIs
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/v1/ledger/transactions | SERVICE | Post transaction |
| GET | /api/v1/ledger/transactions/{id} | Bearer | Get transaction |
| GET | /api/v1/ledger/accounts/{id}/entries | Bearer | Account entries |
| POST | /api/v1/ledger/transactions/{id}/reverse | SERVICE | Reverse transaction |
Database
| Table | Key Columns | Description |
|---|---|---|
| ledger_transactions | id, reference, currency, posted_at, status | Transaction headers |
| ledger_entries | id, transaction_id, account_id, type, amount | Debit/credit lines |
| account_balances | account_id, available, pending, currency | Computed balances |
Kafka
Produces: LedgerTransactionCreated, LedgerEntryCreated
Consumes: None (receives via API)
Partition key: account_id
Dependencies
Sync: Called by Payment Service Async: Publishes ledger events
Failure Handling
- Unbalanced entry → reject (debits ≠ credits)
- Duplicate reference → idempotent return
- DB failure → no partial writes (single TX)
Scaling
Write-heavy. Partition by account_id. Optimistic locking on balances.
Security
SERVICE role only for writes. CUSTOMER read own entries.
Observability
Metrics: ledger_processing_latency, ledger_posting_total. Critical path monitoring.