Integration Guide

This guide shows how to integrate the double-entry accounting system with wallet operations.

Integration Pattern

Every wallet operation follows this flow:

1. Create WalletTransaction (existing model)
2. Create Journal Entry (double-entry record)
3. Update Wallet Balances (existing logic)
4. All within a database transaction (ACID compliance)

---

Key Principles

Use Database Transactions

All operations must be wrapped in a database transaction to ensure ACID compliance. If any step fails, everything rolls back.

autoPost Defaults to True

Transactions are posted immediately by default. Only set autoPost: false for flagged/high-risk transactions requiring compliance review.

Always Use Templates

Use the predefined templates from transactionTemplatesService - never create journal entries manually.

Link to WalletTransaction

Always link journal entries to their source wallet transaction using walletTransactionId.

---

Transaction Types

User → User Transfer (P2P)

Step	Action
1	Validate sender has sufficient balance
2	Create WalletTransaction with type USER_TRANSFER_SENT
3	Create journal using getUserTransferTemplate(senderId, recipientId, amount)
4	Deduct from sender balance
5	Add to recipient balance

---

User → Vendor Payment

Step	Action
1	Validate user has sufficient balance (amount + fee)
2	Create WalletTransaction with type PAYMENT
3	Create journal using getUserPaymentTemplate(userId, vendorId, amount, fee)
4	Deduct (amount + fee) from user balance
5	Add amount to vendor balance

Note: Fee goes to platform revenue (account 4110)

---

Wallet Topup

Step	Action
1	Process external payment (mobile money, etc.)
2	Create WalletTransaction with type TOPUP
3	Create journal using getUserTopupTemplate(userId, amount, source)
4	Add amount to user balance

---

Cash Withdrawal

Step	Action
1	Validate user has sufficient balance (amount + fee)
2	Create WalletTransaction with type WITHDRAWAL
3	Create journal using getUserWithdrawalTemplate(userId, vendorId, amount, fee)
4	Deduct (amount + fee) from user balance
5	Add amount to vendor cash-on-hand

---

Refund

Step	Action
1	Get original transaction details
2	Create WalletTransaction with type REFUND
3	Create journal using getUserRefundTemplate(userId, amount, reason)
4	Add amount back to original payer
5	Deduct from original recipient

Note: Refunds require approval, use autoPost: false

---

Error Handling

Transaction Rollback

If any operation fails, the entire transaction is rolled back. No partial state is persisted.

Balance Validation

Always validate balance before deducting:

Check	Description
Sufficient balance	User/vendor has enough funds
Positive amount	Transaction amount > 0
Valid entities	Sender and recipient exist

Duplicate Detection

Check for duplicate transactions within the last minute using same entityId, type, and amount.

---

Journal Entry Options

Option	Type	Default	Description
walletTransactionId	string	-	Link to source transaction (required)
actorId	string	-	User/admin performing action
ipAddress	string	-	Request IP for audit
requestId	string	-	Request tracking ID
autoPost	boolean	true	Post immediately vs pending review
amlStatus	string	-	Set if flagged for AML review

---

When to Disable autoPost

Scenario	Reason
High-value payments	Compliance review threshold
AML flagged transaction	Suspicious activity detected
Refund processing	Requires admin approval
Manual adjustments	Finance team review

---

Reconciliation

Daily reconciliation runs automatically at 2 AM and verifies:

• Wallet balances match ledger entries
• All transactions have corresponding journal entries
• No orphaned entries exist

If discrepancies are found, alerts are generated automatically.

---

Benefits of Integration

Before	After
No audit trail	Complete audit trail with tamper detection
Balance discrepancies hard to trace	Automatic reconciliation verification
No regulatory compliance	Double-entry bookkeeping compliance
Partial failures possible	ACID-compliant (all-or-nothing)

---

Related Documentation

• Transaction Templates Reference - All available templates
• Ledger Service API - Detailed service methods
• Troubleshooting - Common issues and solutions