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

# Adding Bank Accounts

> Register your organization's bank accounts in Agatabo and set up cash tracking

## Overview

Before you can track transactions, you need to add your bank accounts to Agatabo. This creates a record for each physical account and automatically sets up the ledger system to track balances.

## Before You Begin

<Note>
  **Prerequisites:**

  * You have `bank_accounts:write` permission
  * You know the names and types of your bank accounts
  * You have current balance information if setting opening balances
</Note>

## What Happens When You Add an Account

When you create a bank account, Agatabo automatically:

1. **Creates a bank account record** with your specified name and type
2. **Creates a CASH ledger account** behind the scenes to track transactions
3. **Sets initial balance to zero** (you can adjust this later if needed)
4. **Makes it available** for use in deposits, loans, expenses, and other transactions
5. **Sets as default** (first account only - automatically becomes the default account)

## Step-by-Step Instructions

### Step 1: Navigate to Bank Accounts

<Steps>
  <Step title="Open Bank Accounts">
    Click "Bank Accounts" in the sidebar or navigation menu
  </Step>

  <Step title="Click Add Bank Account">
    Opens the bank account creation form
  </Step>
</Steps>

### Step 2: Enter Account Information

Fill in the required fields:

| Field         | Description                         | Required | Validation                              |
| ------------- | ----------------------------------- | -------- | --------------------------------------- |
| **Name**      | Descriptive name for the account    | Yes      | Must be unique within your organization |
| **Type**      | SAVINGS or CURRENT                  | Yes      | Cannot be changed after creation        |
| **Is Active** | Whether account is currently in use | No       | Defaults to `true` (active)             |

<Note>
  **Account names must be unique**: Each account name must be unique within your organization. If you try to create an account with a duplicate name, you'll receive an error: "This account name is already used in the organization."
</Note>

<Note>
  **Naming tips**: Use descriptive names that help you identify the account easily:

  * Include the bank name: "BK Operations Account", "Equity Savings Account"
  * Include last 4 digits: "BK Current \*\*\*1234", "Equity Savings \*\*\*5678"
  * Include purpose: "Loan Disbursement Account", "Emergency Reserve Fund"
</Note>

### Step 3: Choose Account Type

Select the appropriate type for your account:

<Tabs>
  <Tab title="CURRENT">
    **Current Account (Checking)**

    **Use for:**

    * Daily operational expenses
    * Loan disbursements and repayments
    * Frequent transactions
    * Payment processing
    * Member deposits

    **Characteristics:**

    * High transaction volume
    * Easy withdrawals
    * Lower or no interest
    * Primary operating account

    **Note**: Most tontines use a CURRENT account as their primary default account. At least one active CURRENT account is required.
  </Tab>

  <Tab title="SAVINGS">
    **Savings Account**

    **Use for:**

    * Long-term reserves
    * Emergency funds
    * Dividend accumulation
    * Investment savings
    * Statutory reserves

    **Characteristics:**

    * Lower transaction volume
    * Earns interest
    * Restricted withdrawals
    * Long-term storage

    **Note**: Savings accounts are typically used for funds that shouldn't be spent on regular operations.
  </Tab>
</Tabs>

**Cannot change type**: Once you create an account with a specific type (SAVINGS or CURRENT), you cannot change it later. Delete and recreate if needed (subject to deletion constraints).

### Step 4: Submit

<Steps>
  <Step title="Review information">
    Double-check the name and type before submitting
  </Step>

  <Step title="Click Save or Add Account">
    Creates the bank account record
  </Step>

  <Step title="Verify creation">
    Account should appear in the bank accounts list with 0.00 balance
  </Step>
</Steps>

## First Account Special Behavior

**Your first bank account is automatically set as the default account.**

**What this means**:

* When recording transactions, this account will be pre-selected
* Used automatically when no specific account is selected
* Simplifies data entry for common operations

**For subsequent accounts**:

* New accounts are NOT automatically set as default
* You must manually set a different account as default if desired
* Use the "Set as Default" action on the account you want to make primary

[Learn how to change the default account →](#changing-the-default-account)

## Setting Opening Balances

If your bank account already has money in it when you add it to Agatabo, you need to adjust the opening balance:

### When to Adjust Opening Balance

**Adjust opening balance if**:

* You're starting to use Agatabo mid-year
* The physical bank account has existing funds
* You're migrating from another system
* Your bank statement shows a non-zero balance

**Skip if**:

* You're starting fresh with new accounts
* Account actually has zero balance
* You'll be importing historical transactions

### How to Adjust Opening Balance

<Steps>
  <Step title="Navigate to bank account">
    Find the newly created account in the list
  </Step>

  <Step title="Click Adjust Balance">
    Look for "Adjust Balance" or "Set Opening Balance" action
  </Step>

  <Step title="Enter current balance">
    Input the balance from your most recent bank statement
  </Step>

  <Step title="Add description">
    Example: "Opening balance as of June 1, 2026 per bank statement"
  </Step>

  <Step title="Submit">
    Creates a CASH\_OPENING journal entry
  </Step>
</Steps>

**What happens**:

```
Journal Entry (CASH_OPENING):
Dr CASH (Your Bank Account)    5,000,000
   Cr OPENING_EQUITY           5,000,000

Result: Bank account now shows 5,000,000 RWF balance
```

<Warning>
  **Important opening balance rules:**

  * Only adjust opening balance ONCE when you first set up the account
  * Do this BEFORE recording any transactions
  * After initial setup, all balance changes should come from actual transactions
  * Cannot adjust opening balance after accounting period is closed
  * Cannot create negative opening equity (total adjustments cannot exceed equity)
</Warning>

## Changing the Default Account

If you want to change which account is the default:

<Steps>
  <Step title="Navigate to bank accounts">
    View the list of all bank accounts
  </Step>

  <Step title="Find the target account">
    Locate the account you want to make default
  </Step>

  <Step title="Click Set as Default">
    Action button or menu option
  </Step>

  <Step title="Confirm">
    Previous default is automatically unset, new account becomes default
  </Step>
</Steps>

**Technical details**:

* Only one account can be default at a time
* System automatically unsets previous default
* Changes take effect immediately

## Multiple Bank Accounts

Most organizations benefit from having multiple accounts for different purposes:

### Example Setup

**Recommended structure**:

1. **BK Current Account** (CURRENT, Default)
   * Purpose: Primary operations
   * Use for: Daily deposits, small expenses, general transactions
   * Balance: Moderate operating cash

2. **Equity Savings Account** (SAVINGS)
   * Purpose: Long-term reserves
   * Use for: Emergency funds, statutory reserves
   * Balance: High reserve funds

3. **Loan Disbursement Account** (CURRENT)
   * Purpose: Dedicated for loans
   * Use for: Loan disbursements and repayments only
   * Balance: Varies based on loan activity

4. **Dividend Account** (SAVINGS)
   * Purpose: Dividend accumulation
   * Use for: Collecting profits before distribution
   * Balance: Accumulated undistributed dividends

### Benefits of Multiple Accounts

**Financial control**:

* Separate operational funds from reserves
* Track specific purposes (loans, dividends, etc.)
* Prevent accidental use of restricted funds

**Reporting**:

* Clearer cash flow analysis
* Better audit trail
* Easier reconciliation

**Risk management**:

* Diversify across banks
* Protect reserve funds
* Maintain minimum balances per purpose

## Active vs Inactive Accounts

### Active Accounts

**Characteristics**:

* Available in transaction dropdowns
* Can receive deposits and disbursements
* Appear in default account selection
* Fully functional

**Default state**: All accounts are active when created (unless you explicitly set `isActive: false`)

### Inactive Accounts

**Characteristics**:

* Hidden from transaction dropdowns
* Cannot be selected for new transactions
* Historical transactions remain visible
* Balance still tracked

**When to inactivate**:

* Closed physical bank account
* No longer using this account
* Temporary suspension
* Migrating to new account

**How to inactivate**:

1. Navigate to bank account
2. Click Edit or Update
3. Uncheck "Is Active" or set to inactive
4. Save changes

**Constraints**:

* Cannot inactivate if it's the only active CURRENT account
* Cannot inactivate the default account (set another as default first)

## Validation and Constraints

### During Creation

**Validations applied**:

✅ **Name uniqueness**: Account name must be unique within organization

* Error: "This account name is already used in the organization"

✅ **Type validity**: Must be exactly "SAVINGS" or "CURRENT"

* Error: "Invalid account type"

✅ **Organization header**: Organization ID must be provided

* Error: "Organization header is required"

### Common Errors

| Error Message                                           | Cause                        | Solution                    |
| ------------------------------------------------------- | ---------------------------- | --------------------------- |
| "This account name is already used in the organization" | Duplicate name               | Choose a different name     |
| "Invalid account type"                                  | Type not SAVINGS or CURRENT  | Use valid type              |
| "Organization header is required"                       | Missing organization context | System error - refresh page |

## After Adding an Account

### Next Steps

**Immediate**:

1. ✅ Adjust opening balance if needed
2. ✅ Verify account appears in accounts list
3. ✅ Check balance shows correctly
4. ✅ Set as default if desired (for non-first accounts)

**Within first week**:

1. 📝 Record initial transactions
2. 📝 Test deposits and expenses
3. 📝 Verify transaction history appears
4. 📝 Reconcile with bank statement

### What You Can Do with the Account

**Supported operations**:

* Record savings deposits (credits CASH)
* Disburse loans (debits CASH)
* Record loan payments (credits CASH)
* Pay expenses (debits CASH)
* Record bank charges (debits CASH)
* Transfer between accounts (manual journal entries)
* Adjust opening balance (one-time)
* View transaction history
* Reconcile with bank statements

## Permissions Required

| Action                 | Permission            | Scope |
| ---------------------- | --------------------- | ----- |
| Create bank account    | `bank_accounts:write` | ANY   |
| View bank accounts     | `bank_accounts:read`  | ANY   |
| Set default account    | `bank_accounts:write` | ANY   |
| Adjust opening balance | `bank_accounts:write` | ANY   |
| Update account details | `bank_accounts:write` | ANY   |

<Note>
  **Administrator or Accountant role**: Typically, only users with Administrator or Accountant roles have `bank_accounts:write` permission. Regular members cannot create or modify bank accounts.
</Note>

## Troubleshooting

### "This account name is already used"

**Problem**: Trying to create account with duplicate name

**Solution**:

1. Check existing accounts for similar names
2. Choose a more specific name (add bank name, account number, purpose)
3. Delete unused duplicate account if it exists

### Account Created But Not Appearing

**Problem**: Created account but don't see it in lists

**Solution**:

1. Refresh the page
2. Check if account was marked inactive during creation
3. Verify you're viewing the correct organization
4. Check browser console for errors

### Cannot Set as Default

**Problem**: "Set as Default" button not working

**Solution**:

1. Ensure account is active
2. Verify you have `bank_accounts:write` permission
3. Check if account already is the default
4. Try refreshing the page

## Related Topics

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

  <Card title="Recording Transactions" icon="file-invoice-dollar" href="/tontines/bank-accounts/recording-transactions">
    Start using your bank accounts
  </Card>

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

  <Card title="General Ledger" icon="book" href="/tontines/general-ledger/overview">
    Understand ledger integration
  </Card>
</CardGroup>