Recording Bank Transactions

Overview

Bank account transactions in Agatabo are recorded automatically through journal entries when you perform financial operations. Every transaction that affects cash creates journal lines that debit or credit the CASH ledger account linked to your bank account.

Important: You don’t manually record “bank transactions.” Instead, you perform business operations (record deposits, disburse loans, pay expenses), and Agatabo automatically creates the accounting entries that update your bank account balances.

How Automatic Recording Works

The Ledger Connection

Each bank account is backed by a CASH ledger account:

Bank Account: "BK Operations Account"
    ↓ links to ↓
CASH Ledger Account (scopeKey: "cash:{bankAccountId}")
    ↓ tracks ↓
Balance: Updated automatically via journal entries

When you perform an operation:

Operation creates a journal entry with specific kind (e.g., SAVINGS_DEPOSIT)
Journal entry contains balanced debit/credit lines
One or more lines affect CASH ledger account(s)
Database triggers update ledger balances instantly
Bank account balance reflects the change

Transaction Types That Affect Bank Accounts

1. Savings Deposits (Increases Balance)

Operation: Member deposits money into savings Endpoint: POST /savings/record Journal Entry:

Kind: SAVINGS_DEPOSIT
Date: Deposit date

Dr CASH (Bank Account)         Amount
   Cr SAVINGS (Member Account)  Amount

Effect on Bank Account: ✅ Increases balance (cash received) Example:

Member Jane deposits 50,000 RWF:

Dr CASH (BK Operations)    50,000
   Cr SAVINGS (Jane)       50,000

Bank Account Balance:
Before: 1,000,000 RWF
After:  1,050,000 RWF (increased by 50,000)

Where to record: Deposits → Record Deposit Learn more about recording deposits →

2. Loan Disbursements (Decreases Balance)

Operation: Organization lends money to member Endpoints:

POST /loans (initial disbursement)
POST /loans/:id/modify (additional disbursement via top-up)

Journal Entry:

Kind: LOAN_DISBURSEMENT or LOAN_MODIFICATION
Date: Disbursement date

Dr LOAN_RECEIVABLE (Loan)     Amount
   Cr CASH (Bank Account)      Amount

Effect on Bank Account: ❌ Decreases balance (cash given to borrower) Example:

Disburse 500,000 RWF loan to John:

Dr LOAN_RECEIVABLE (John's Loan)  500,000
   Cr CASH (BK Operations)        500,000

Bank Account Balance:
Before: 1,050,000 RWF
After:    550,000 RWF (decreased by 500,000)

Where to record: Loans → Create Loan or Modify Loan Learn more about creating loans →

3. Loan Payments (No Direct Effect)

Operation: Member repays loan installment Endpoint: POST /loans/:id/payments Journal Entry:

Kind: LOAN_PAYMENT
Date: Payment date

Dr SAVINGS (Member)                  TotalAmount
   Cr LOAN_RECEIVABLE (Loan)         PrincipalPortion
   Cr INTEREST_RECEIVABLE (Loan)     InterestPortion
   Cr PENALTY_RECEIVABLE (Loan)      PenaltyPortion

Effect on Bank Account: ⚠️ No direct effect (internal transfer from member savings to loan receivable) Example:

John pays 55,000 RWF (50,000 principal + 5,000 interest):

Dr SAVINGS (John)                55,000
   Cr LOAN_RECEIVABLE (Loan)    50,000
   Cr INTEREST_RECEIVABLE       5,000

Bank Account Balance: UNCHANGED
(Money moved from member's savings to reduce loan, no cash leaves organization)

Where to record: Loans → Record Payment Learn more about loan payments →

4. Expense Payments (Decreases Balance)

Operation: Organization pays operational expense Endpoint: POST /expenses Journal Entry:

Kind: EXPENSE_PAYMENT
Date: Expense date

Dr OPERATING_EXPENSE (Category)  Amount
   Cr CASH (Bank Account)        Amount

Effect on Bank Account: ❌ Decreases balance (cash paid to supplier/vendor) Example:

Pay 30,000 RWF office rent:

Dr OPERATING_EXPENSE (Rent)  30,000
   Cr CASH (BK Operations)   30,000

Bank Account Balance:
Before: 550,000 RWF
After:  520,000 RWF (decreased by 30,000)

Where to record: Expenses → Record Expense Learn more about expenses →

5. Bank Charges (Decreases Balance)

Operation: Bank deducts fees or charges Endpoint: POST /expenses with bankChargeAmount field Journal Entry:

Kind: BANK_CHARGE
Date: Charge date
ParentEntry: Links to main expense/asset/loan entry

Dr BANK_CHARGE_EXPENSE  Amount
   Cr CASH (Bank Account)  Amount

Effect on Bank Account: ❌ Decreases balance (bank fee deducted) Example:

Bank charges 2,000 RWF transaction fee:

Dr BANK_CHARGE_EXPENSE  2,000
   Cr CASH (BK Operations)  2,000

Bank Account Balance:
Before: 520,000 RWF
After:  518,000 RWF (decreased by 2,000)

Where to record:

Expenses → Record Expense → Bank Charge Amount field
Assets → Purchase Asset → Bank Charge field

Bank charges are separate entries: When you include a bank charge amount with an expense or asset, Agatabo creates TWO journal entries: one for the main transaction, and a separate BANK_CHARGE entry.

6. Dividend Distributions (Decreases Balance)

Operation: Organization distributes profits to members Endpoint: POST /dividends/:poolId/distribute Journal Entry:

Kind: DIVIDEND_DISTRIBUTION
Date: Distribution date

Dr RETAINED_EARNINGS        Amount
   Cr CASH (Bank Account)   Amount (if cash distribution)
   Cr SAVINGS (Member)      Amount (if credited to savings)

Effect on Bank Account: ❌ Decreases balance (if cash distribution) or ⚠️ No effect (if credited to savings) Example (Cash Distribution):

Distribute 100,000 RWF dividend to member:

Dr RETAINED_EARNINGS       100,000
   Cr CASH (BK Operations) 100,000

Bank Account Balance:
Before: 518,000 RWF
After:  418,000 RWF (decreased by 100,000)

Where to record: Dividends → Distribute Dividends Learn more about dividends →

7. Reserve Operations (Varies)

Reserve Top-up (Decreases Balance):

Kind: RESERVE_TOP_UP

Dr RESERVE_ALLOCATION      Amount
   Cr CASH (Bank Account)  Amount

Reserve Release (Increases Balance):

Kind: RESERVE_RELEASE

Dr CASH (Bank Account)        Amount
   Cr RESERVE_ALLOCATION      Amount

Where to record: Reserves → Allocate or Release Reserves Learn more about reserves →

8. Entry Fees (Increases Balance)

Operation: New member pays entry fee Endpoint: POST /organization-users/:id/entry-fee Journal Entry:

Kind: ENTRY_FEE
Date: Payment date

Dr CASH (Bank Account)        Amount
   Cr ENTRY_FEE_INCOME        Amount

Effect on Bank Account: ✅ Increases balance (fee received) Learn more about entry fees →

9. Opening Balance Adjustments (Sets Balance)

Operation: Set initial bank account balance when starting Agatabo Endpoint: PATCH /bank-accounts/:id/adjust-balance Journal Entry:

Kind: CASH_OPENING
Date: Adjustment date

Dr CASH (Bank Account)  Amount
   Cr OPENING_EQUITY    Amount

Effect on Bank Account: Sets balance to target amount Example:

Adjust opening balance to 5,000,000 RWF:

Dr CASH (BK Operations)  5,000,000
   Cr OPENING_EQUITY     5,000,000

Bank Account Balance:
Before: 0 RWF
After:  5,000,000 RWF

Where to record: Bank Accounts → Select Account → Adjust Balance Learn more about opening balances →

10. Bank Transfers (Decreases One, Increases Another)

Operation: Transfer money between your bank accounts Method: Manual journal entry Journal Entry:

Kind: MANUAL_JOURNAL
Description: Transfer between accounts

Dr CASH (Destination Account)  Amount
   Cr CASH (Source Account)    Amount

Effect on Bank Accounts:

Source: ❌ Decreases balance
Destination: ✅ Increases balance

Total cash: Unchanged (money moved internally) Where to record: General Ledger → Manual Journal Entries Learn more about transfers →

Selecting Bank Account

When recording operations that affect cash, you must select which bank account to use:

Account Selection Fields

Appears in:

Deposit forms (“Bank Account” dropdown)
Loan creation (“Disbursement Account” dropdown)
Loan modification (“Bank Account” dropdown)
Expense forms (“Bank Account” dropdown)
Dividend distribution (“Payment Account” dropdown)
Reserve operations (“Bank Account” dropdown)

Default behavior:

Pre-selects the default bank account
You can change to any active account
System validates account is active

Look for Bank Account field

Appears in most financial transaction forms

Verify pre-selected account

Default account is auto-selected

Change if needed

Select different account from dropdown if appropriate

Complete transaction

Selected account balance updates automatically

Always select the correct account: This ensures your Agatabo balances match your actual bank statements for each account. If deposit goes to Account A physically, select Account A in Agatabo.

Viewing Bank Account Activity

Viewing Transaction History

To see all transactions for a specific bank account:

Navigate to Bank Accounts

Click “Bank Accounts” in sidebar

Select an account

Click on the bank account name

View transaction list

See all journal entries affecting this account

Filter and search

Use date range, entry kind filters if available

Information shown:

Transaction date
Entry kind (SAVINGS_DEPOSIT, EXPENSE_PAYMENT, etc.)
Description
Debit or Credit amount
Running balance (if available)
Related entity (member, loan, expense)

Viewing via General Ledger

Alternatively, view transactions through the ledger system:

Navigate to General Ledger

Click “General Ledger” or “Accounting”

Search for CASH account

Find CASH ledger account for your bank

View account activity

See all journal lines affecting this ledger account

Learn more about the general ledger →

Transaction Validation

Automatic Validations

When posting transactions affecting bank accounts, Agatabo validates: Balance Constraints:

✅ Cash balance cannot go negative (except when explicitly allowed for opening balances)
✅ Sufficient funds for disbursements and expenses
✅ Available balance calculation accounts for reserves

Accounting Period:

✅ Cannot post to closed accounting periods
✅ Transaction date must be in open period

Journal Entry Rules:

✅ Debits must equal credits (balanced entry)
✅ All amounts must be positive
✅ All ledger accounts must be active
✅ Idempotency key prevents duplicates

Account Status:

✅ Bank account must be active
✅ Cannot use inactive accounts for new transactions

Idempotency Protection

Every transaction uses an idempotency key to prevent duplicates: How it works:

System generates unique key per operation
If request is retried with same key, returns existing transaction
Prevents accidental double-posting
Safe for network retries

Understanding Journal Entries

What is a Journal Entry?

A journal entry is the accounting record created for each financial transaction: Components:

Kind: Type of transaction (SAVINGS_DEPOSIT, LOAN_PAYMENT, etc.)
Date: Transaction date
Lines: Individual debits and credits
Status: POSTED (active) or REVERSED (voided)

Example:

Entry ID: JE-12345
Kind: SAVINGS_DEPOSIT
Date: 2026-06-11
Status: POSTED

Lines:
  1. Dr CASH (BK Operations)    50,000  [increases bank balance]
  2. Cr SAVINGS (Jane)          50,000  [increases Jane's savings]

Total Debits: 50,000 = Total Credits: 50,000 ✅

Learn more about journal entries →

Summary Table

Operation	Endpoint/Action	Entry Kind	Bank Balance Change
Savings Deposit	POST /savings/record	SAVINGS_DEPOSIT	✅ Increases
Loan Disbursement	POST /loans	LOAN_DISBURSEMENT	❌ Decreases
Loan Modification	POST /loans/:id/modify	LOAN_MODIFICATION	❌ Decreases (if top-up)
Loan Payment	POST /loans/:id/payments	LOAN_PAYMENT	⚠️ No effect
Expense Payment	POST /expenses	EXPENSE_PAYMENT	❌ Decreases
Bank Charge	POST /expenses (with amount)	BANK_CHARGE	❌ Decreases
Dividend Distribution	POST /dividends/distribute	DIVIDEND_DISTRIBUTION	❌ Decreases (cash) / ⚠️ No effect (savings)
Reserve Top-up	POST /reserves/allocate	RESERVE_TOP_UP	❌ Decreases
Reserve Release	POST /reserves/release	RESERVE_RELEASE	✅ Increases
Entry Fee	POST /users/:id/entry-fee	ENTRY_FEE	✅ Increases
Opening Balance	PATCH /accounts/:id/adjust	CASH_OPENING	Sets to target
Bank Transfer	Manual Journal Entry	MANUAL_JOURNAL	❌ Source / ✅ Destination

Best Practices

Transaction recording tips:

Always select the correct bank account when recording transactions
Verify bank account balance matches physical statement regularly
Use consistent account selection (operations → Account A, loans → Account B)
Document transfers between accounts with clear descriptions
Reconcile monthly to catch discrepancies early
Review transaction history to understand balance changes
Use opening balance adjustment only once during setup
Don’t try to manually adjust balances (use proper transaction types)
Monitor for negative balance warnings
Ensure transaction dates are accurate

Troubleshooting

Balance Doesn’t Match Bank Statement

Problem: Agatabo shows different balance than physical bank Solutions:

Review all transactions in Agatabo for the account
Compare against bank statement line-by-line
Check for missing deposits or expenses
Verify all bank charges were recorded
Look for transactions recorded to wrong account
Run reconciliation report

Learn about reconciliation →

Cannot Record Transaction (Insufficient Funds)

Problem: “Insufficient cash balance” error Solutions:

Check current bank account balance
Verify you selected correct account
Account for reserved funds (reserves reduce available balance)
Transfer funds from another account if needed
Verify member has sufficient savings for loan payment

Transaction Not Appearing

Problem: Recorded operation but don’t see bank transaction Solutions:

Refresh the bank account page
Check if you selected different bank account
Verify transaction was successfully posted (check journal entries)
Some operations don’t affect bank directly (loan payments debit savings)
Check accounting period is open

Permissions Required

Action	Permission	Scope
View bank account activity	`bank_accounts:read`	ANY
Record deposits	`savings:write`	ANY
Disburse loans	`loans:write`	ANY
Record loan payments	`loans:write`	ANY
Record expenses	`expenses:write`	ANY
View journal entries	`ledger:read`	ANY
Create manual entries	`ledger:write`	ANY

Bank Accounts Overview

Understand bank account management

Recording Deposits

How to record member savings

Recording Expenses

How to pay organization expenses

General Ledger

Understand the accounting system

Viewing Journal Entries

See all accounting transactions

Reconciliation

Match with bank statements

​Overview

​How Automatic Recording Works

​The Ledger Connection

​Transaction Types That Affect Bank Accounts

​1. Savings Deposits (Increases Balance)

​2. Loan Disbursements (Decreases Balance)

​3. Loan Payments (No Direct Effect)

​4. Expense Payments (Decreases Balance)

​5. Bank Charges (Decreases Balance)

​6. Dividend Distributions (Decreases Balance)

​7. Reserve Operations (Varies)

​8. Entry Fees (Increases Balance)

​9. Opening Balance Adjustments (Sets Balance)

​10. Bank Transfers (Decreases One, Increases Another)

​Selecting Bank Account

​Account Selection Fields

​Viewing Bank Account Activity

​Viewing Transaction History

​Viewing via General Ledger

​Transaction Validation

​Automatic Validations

​Idempotency Protection

​Understanding Journal Entries

​What is a Journal Entry?

​Summary Table

​Best Practices

​Troubleshooting

​Balance Doesn’t Match Bank Statement

​Cannot Record Transaction (Insufficient Funds)

​Transaction Not Appearing

​Permissions Required

​Related Topics

Bank Accounts Overview

Recording Deposits

Recording Expenses

General Ledger

Viewing Journal Entries

Reconciliation

Overview

How Automatic Recording Works

The Ledger Connection

Transaction Types That Affect Bank Accounts

1. Savings Deposits (Increases Balance)

2. Loan Disbursements (Decreases Balance)

3. Loan Payments (No Direct Effect)

4. Expense Payments (Decreases Balance)

5. Bank Charges (Decreases Balance)

6. Dividend Distributions (Decreases Balance)

7. Reserve Operations (Varies)

8. Entry Fees (Increases Balance)

9. Opening Balance Adjustments (Sets Balance)

10. Bank Transfers (Decreases One, Increases Another)

Selecting Bank Account

Account Selection Fields

Viewing Bank Account Activity

Viewing Transaction History

Viewing via General Ledger

Transaction Validation

Automatic Validations

Idempotency Protection

Understanding Journal Entries

What is a Journal Entry?

Summary Table

Best Practices

Troubleshooting

Balance Doesn’t Match Bank Statement

Cannot Record Transaction (Insufficient Funds)

Transaction Not Appearing

Permissions Required

Related Topics