> ## Documentation Index
> Fetch the complete documentation index at: https://help.agatabo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recording Bank Transactions

> Understand how deposits, disbursements, expenses, and other operations automatically update bank account balances through journal entries

## 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.

<Note>
  **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.
</Note>

## 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**:

1. Operation creates a journal entry with specific kind (e.g., SAVINGS\_DEPOSIT)
2. Journal entry contains balanced debit/credit lines
3. One or more lines affect CASH ledger account(s)
4. Database triggers update ledger balances instantly
5. 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 →](/tontines/deposits/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 →](/tontines/loans/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 →](/tontines/loans/recording-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 →](/tontines/expenses/recording-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

<Note>
  **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.
</Note>

***

### 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 →](/tontines/dividends/distributing-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 →](/tontines/reserves/overview)

***

### 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 →](/tontines/organization-users/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 →](/tontines/bank-accounts/adding-bank-accounts#setting-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 →](/tontines/bank-accounts/bank-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

<Steps>
  <Step title="Look for Bank Account field">
    Appears in most financial transaction forms
  </Step>

  <Step title="Verify pre-selected account">
    Default account is auto-selected
  </Step>

  <Step title="Change if needed">
    Select different account from dropdown if appropriate
  </Step>

  <Step title="Complete transaction">
    Selected account balance updates automatically
  </Step>
</Steps>

<Note>
  **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.
</Note>

## Viewing Bank Account Activity

### Viewing Transaction History

To see all transactions for a specific bank account:

<Steps>
  <Step title="Navigate to Bank Accounts">
    Click "Bank Accounts" in sidebar
  </Step>

  <Step title="Select an account">
    Click on the bank account name
  </Step>

  <Step title="View transaction list">
    See all journal entries affecting this account
  </Step>

  <Step title="Filter and search">
    Use date range, entry kind filters if available
  </Step>
</Steps>

**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:

<Steps>
  <Step title="Navigate to General Ledger">
    Click "General Ledger" or "Accounting"
  </Step>

  <Step title="Search for CASH account">
    Find CASH ledger account for your bank
  </Step>

  <Step title="View account activity">
    See all journal lines affecting this ledger account
  </Step>
</Steps>

[Learn more about the general ledger →](/tontines/general-ledger/overview)

## 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 →](/tontines/general-ledger/viewing-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

<Note>
  **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
</Note>

## Troubleshooting

### Balance Doesn't Match Bank Statement

**Problem**: Agatabo shows different balance than physical bank

**Solutions**:

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

[Learn about reconciliation →](/tontines/bank-accounts/reconciliation)

### Cannot Record Transaction (Insufficient Funds)

**Problem**: "Insufficient cash balance" error

**Solutions**:

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

### Transaction Not Appearing

**Problem**: Recorded operation but don't see bank transaction

**Solutions**:

1. Refresh the bank account page
2. Check if you selected different bank account
3. Verify transaction was successfully posted (check journal entries)
4. Some operations don't affect bank directly (loan payments debit savings)
5. 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   |

## Related Topics

<CardGroup cols={2}>
  <Card title="Bank Accounts Overview" icon="building-columns" href="/tontines/bank-accounts/overview">
    Understand bank account management
  </Card>

  <Card title="Recording Deposits" icon="piggy-bank" href="/tontines/deposits/recording-deposits">
    How to record member savings
  </Card>

  <Card title="Recording Expenses" icon="receipt" href="/tontines/expenses/recording-expenses">
    How to pay organization expenses
  </Card>

  <Card title="General Ledger" icon="book" href="/tontines/general-ledger/overview">
    Understand the accounting system
  </Card>

  <Card title="Viewing Journal Entries" icon="list" href="/tontines/general-ledger/viewing-journal-entries">
    See all accounting transactions
  </Card>

  <Card title="Reconciliation" icon="check-double" href="/tontines/bank-accounts/reconciliation">
    Match with bank statements
  </Card>
</CardGroup>