Ledger Service

Core service for ACID-compliant journal and ledger entry operations.

Methods Overview

Method	Description
createJournalEntry()	Create journal with ledger entries
reverseJournalEntry()	Create reversing entry
getJournalById()	Retrieve journal with entries
getJournalsByWalletTransaction()	Get journals for a transaction
getLedgerEntriesByEntity()	Get entries for user/vendor

---

createJournalEntry()

Creates a journal entry with associated ledger entries in an ACID transaction.

Parameters:

Parameter	Type	Required	Description
template	JournalEntryTemplate	Yes	Template from Templates Service
metadata	CreateJournalMetadata	Yes	Transaction metadata
session	ClientSession	No	PostgreSQL session

Returns: { journal, ledgerEntries }

Validation:

• Debits must equal credits
• All accounts must exist
• Checks for duplicate entries
• Currency consistency enforced

---

reverseJournalEntry()

Creates a reversing entry for a posted journal entry.

Parameters:

Parameter	Type	Required	Description
journalId	string	Yes	Journal ID to reverse
reason	string	Yes	Reason for reversal
metadata	ReverseJournalMetadata	Yes	Reversal metadata
session	ClientSession	No	PostgreSQL session

Returns: { originalJournal, reversalJournal }

Process:

1. Validates original is POSTED
2. Creates opposite entries (debit ↔ credit)
3. Links entries via reversalOf/reversedBy
4. Original marked as REVERSED
5. New journal posted immediately

Note: Original entry remains in database for audit trail.

---

getJournalById()

Retrieves a journal entry with its associated ledger entries.

Parameters:

Parameter	Type	Required	Description
journalId	string	Yes	Journal ID to retrieve

Returns: Journal with populated ledger entries

---

getJournalsByWalletTransaction()

Retrieves all journal entries linked to a wallet transaction.

Parameters:

Parameter	Type	Required	Description
walletTransactionId	string	Yes	Wallet transaction ID

Returns: Array of journal entries

Use Cases:

• Viewing accounting details for a transaction
• Verifying journal entries were created
• Debugging discrepancies

---

getLedgerEntriesByEntity()

Retrieves all ledger entries for a specific entity.

Parameters:

Parameter	Type	Required	Description
entityId	string	Yes	User or Vendor ID
entityType	string	Yes	"User" or "Vendor"
options.startDate	Date	No	Filter start date
options.endDate	Date	No	Filter end date
options.status	string	No	PENDING, POSTED, REVERSED
options.limit	number	No	Maximum entries

Returns: Array of ledger entries

---

Metadata Types

CreateJournalMetadata

Field	Type	Default	Description
walletTransactionId	string	-	Link to source transaction
actorId	string	-	User/admin performing action
ipAddress	string	-	Request IP for audit
requestId	string	-	Request tracking ID
autoPost	boolean	true	Post immediately (industry standard)
amlFlagged	boolean	false	Flag for AML review

ReverseJournalMetadata

Field	Type	Description
reversedBy	string	Admin performing reversal
ipAddress	string	Request IP
requestId	string	Request tracking ID

---

Error Types

Error	Description
ValidationError	Template validation failed
BalanceError	Debits ≠ Credits
DuplicateError	Duplicate journal for transaction

---

Best Practices

1. Always use templates - Don't create journal templates manually
2. Use PostgreSQL sessions - Wrap operations in transactions
3. Link to wallet transactions - Always provide walletTransactionId
4. Use autoPost appropriately - true for normal, false for review
5. Document reversals - Provide clear reasons for audit trail

---

Related Documentation

• Templates Service
• Transaction Workflows
• Integration Guide