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

# Finance User Guide

> Step-by-step guide to tracking, reconciling, and distributing church finances in Project Zoe.

## Overview

The Financial Reconciliation System helps you track, match, and distribute church finances efficiently. It automates the process of reconciling bank and mobile money transactions, attributing them to members and locations, and calculating distributions according to your church's financial policies.

### Accessing the system

Navigate to **Admin → Financial Management** in the sidebar. You'll find:

* **Accounts** — Manage bank and mobile money accounts
* **Import Transactions** — Upload statements
* **Reconciliation** — Match transactions to members
* **Distributions** — Calculate and track money distributions
* **Category Rules** — Set up automatic categorization
* **Reports** — View financial summaries

### Weekly workflow at a glance

```mermaid theme={null}
flowchart LR
    A([1. Set Up Accounts]) --> B([2. Configure Rules])
    B --> C([3. Import Transactions])
    C --> D([4. Reconciliation])
    D --> E([5. Calculate Distributions])
    E --> F{6. Approval}
    F --> G([7. Execute Transfers])
    G --> H([Reports])

    style A fill:#7C3AED,color:#fff,stroke:none
    style B fill:#7C3AED,color:#fff,stroke:none
    style C fill:#2563EB,color:#fff,stroke:none
    style D fill:#D97706,color:#fff,stroke:none
    style E fill:#DC2626,color:#fff,stroke:none
    style F fill:#DB2777,color:#fff,stroke:none
    style G fill:#6B7280,color:#fff,stroke:none
    style H fill:#059669,color:#fff,stroke:none
```

<Note>Steps 1 and 2 are one-time setup. Steps 3–7 repeat every week.</Note>

***

## Step 1: Set up financial accounts

Before importing any transactions, create the accounts that money flows through.

<Steps>
  <Step title="Go to Financial Management → Accounts and click + New Account" />

  <Step title="Fill in the account details">
    | Field               | Description                                             |
    | ------------------- | ------------------------------------------------------- |
    | **Name**            | e.g. "Central Mobile Money MTN"                         |
    | **Account Number**  | The actual account or phone number                      |
    | **Type**            | Bank, Mobile Money, or Cash                             |
    | **Owner**           | Leave blank for Central; select a location for branches |
    | **Provider / Bank** | e.g. "MTN", "Centenary Bank"                            |
    | **Status**          | Active                                                  |
  </Step>

  <Step title="Click Save and repeat for each account" />
</Steps>

### Recommended account structure

<Tabs>
  <Tab title="Central">
    | Account Name                     | Type         |
    | -------------------------------- | ------------ |
    | Central Mobile Money (MTN)       | Mobile Money |
    | Central Bank Account (Centenary) | Bank         |
    | Other Ministries Account         | Bank         |
    | Operations Account               | Bank         |
    | Donations Account                | Bank         |
    | Projects Account                 | Bank         |
    | Welfare Account                  | Bank         |
  </Tab>

  <Tab title="Locations">
    | Account Name                | Type | Owner          |
    | --------------------------- | ---- | -------------- |
    | Kampala Branch Bank Account | Bank | Kampala Branch |
    | Entebbe Branch Bank Account | Bank | Entebbe Branch |
  </Tab>
</Tabs>

***

## Step 2: Set up category rules

Category rules automatically classify transactions based on date, time, or keywords — saving significant manual work during reconciliation.

### Default categories

| Category          | When used                                         |
| ----------------- | ------------------------------------------------- |
| **Tithe**         | Regular tithes — the default for all transactions |
| **Offering**      | Giving during service times                       |
| **Donation**      | Special one-off donations                         |
| **Arise & Build** | Building/project fund (typically January)         |

### How to create a rule

<Steps>
  <Step title="Go to Financial Management → Category Rules and click + New Rule" />

  <Step title="Set the rule name, category, and priority">
    Higher priority numbers are evaluated first (range: 0–100).
  </Step>

  <Step title="Set conditions">
    Conditions narrow when the rule fires. Leave a condition blank to apply it to all transactions.

    * **Accounts** — Which accounts this applies to
    * **Keywords** — Words that must appear in the narration
    * **Date Range** — e.g. Jan 1–31 for Arise & Build
    * **Time Range** — e.g. 09:00–12:00 for service offerings
    * **Days of Week** — e.g. Sunday only
  </Step>

  <Step title="Click Save" />
</Steps>

### Rules to create from the start

<AccordionGroup>
  <Accordion title="Sunday Service Offerings — Priority 5">
    | Field    | Value                |
    | -------- | -------------------- |
    | Category | Offering             |
    | Accounts | Central Mobile Money |
    | Days     | Sunday               |
    | Time     | 09:00 – 12:00        |

    Marks Sunday morning mobile money transactions as Offering rather than Tithe.
  </Accordion>

  <Accordion title="January Arise & Build — Priority 10">
    | Field      | Value                             |
    | ---------- | --------------------------------- |
    | Category   | Arise & Build                     |
    | Date Range | January 1 – January 31 (any year) |
    | Keywords   | arise, build, project, building   |

    Catches building-fund transactions throughout January automatically.
  </Accordion>

  <Accordion title="Donation Keywords — Priority 3">
    | Field    | Value                                |
    | -------- | ------------------------------------ |
    | Category | Donation                             |
    | Keywords | donation, donate, gift, contribution |

    Categorizes special donations by narration keyword.
  </Accordion>
</AccordionGroup>

<Tip>
  Anything that doesn't match a rule defaults to **Tithe**. You can always override the category manually during reconciliation.
</Tip>

***

## Step 3: Import transactions

<Steps>
  <Step title="Go to Financial Management → Import Transactions" />

  <Step title="Configure the import">
    * **Account** — Which account these transactions belong to
    * **Default Category** — Usually "Tithe"
    * **Apply service time rules** — Tick this to auto-mark Sunday morning transactions as Offering
  </Step>

  <Step title="Choose your file and click Preview Import">
    The system shows all detected transactions. Review the date, amount, name, phone, narration, and auto-detected category for each row. Rows with errors are highlighted in red. Click any category to change it.
  </Step>

  <Step title="Click Import Transactions">
    A success message shows the count and total amount. Click **Go to Reconciliation** to continue.
  </Step>
</Steps>

### File format requirements

| Column                                                   | Notes                                                 |
| -------------------------------------------------------- | ----------------------------------------------------- |
| Date                                                     | Any common format: DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD |
| Amount                                                   | Numbers only — no currency symbols or commas          |
| Sender Name / Account Name                               | —                                                     |
| Phone Number (mobile money) **or** Account Number (bank) | —                                                     |
| Narration / Description / Reference                      | Optional but improves auto-categorization             |

***

## Step 4: Reconciliation

Reconciliation links each transaction to a known church member — or flags it for follow-up.

### The workbench

Go to **Financial Management → Reconciliation**. Three tabs:

* **Pending Review** — Transactions waiting to be matched
* **Matched** — Reconciled transactions
* **Disputed** — Transactions flagged for follow-up

### Confidence scores

| Score     | Meaning             | Colour    |
| --------- | ------------------- | --------- |
| 90–100%   | Very likely correct | 🟢 Green  |
| 70–89%    | Probably correct    | 🟡 Yellow |
| Below 70% | Less certain        | 🟠 Orange |

### Your matching options

<Tabs>
  <Tab title="Quick approve">
    If the suggestion is correct, click **Approve**. The transaction moves to "Matched" and the phone number is saved for future transactions (improving future confidence scores).
  </Tab>

  <Tab title="Edit / manual match">
    Click **Edit** to open the match window:

    1. Search for the contact by name
    2. Confirm or update their location
    3. Tick **Add New Payment Method** if they used a different phone number
    4. Confirm the category
    5. Click **Save Match**
  </Tab>

  <Tab title="Bulk approve">
    1. Tick the boxes next to multiple transactions
    2. Click **Approve All High Confidence (>90%)**

    Only transactions meeting the threshold are approved — the rest stay in Pending for individual review.
  </Tab>

  <Tab title="Mark as disputed">
    Click **Mark as Disputed** when you can't identify the sender. The transaction moves to the Disputed tab. Return to it once you have more information.
  </Tab>
</Tabs>

### Recommended matching order

1. **High confidence (>90%)** — Bulk approve in one click
2. **Medium confidence (70–89%)** — Review individually, approve or edit
3. **Low confidence (below 70%)** — Manual match or mark disputed
4. **Disputed items** — Review weekly; escalate after 30 days unresolved

***

## Step 5: Calculate distributions

After reconciling the period's transactions, generate the distribution.

<Steps>
  <Step title="Go to Financial Management → Distributions and click + New Distribution Batch" />

  <Step title="Configure the batch">
    * **Name** — e.g. "Week 45 2024" or "January 2024"
    * **Period Type** — Weekly, Monthly, or Custom
    * **Date Range** — The period to include
    * **Include** — Tick "Approved matches only" (recommended)
  </Step>

  <Step title="Click Calculate Distributions">
    The system shows a summary by category and a detailed table of every distribution line.
  </Step>

  <Step title="Review and edit if needed">
    Click any amount to edit it manually. The system validates that all totals balance.
  </Step>

  <Step title="Save or submit">
    * **Save as Draft** — Come back and edit later
    * **Submit for Approval** — Send to leadership for review
    * **Approve** — Finalize immediately (requires approval permission)
  </Step>
</Steps>

### Distribution rules

<Tabs>
  <Tab title="Central">
    | Category      | Other Ministries | Operations | Locations                    |
    | ------------- | ---------------- | ---------- | ---------------------------- |
    | Tithe         | 10%              | 30%        | 60% split by member location |
    | Offering      | 10%              | 30%        | 60% split by member location |
    | Donation      | 10%              | —          | 90% → Donations Account      |
    | Arise & Build | 10%              | —          | 90% → Projects Account       |
  </Tab>

  <Tab title="Locations">
    | Category      | To Central      | To Welfare | Retained |
    | ------------- | --------------- | ---------- | -------- |
    | Tithe         | 40%             | 30%        | 30%      |
    | Offering      | 40%             | 30%        | 30%      |
    | Donation      | 10%             | —          | 90%      |
    | Arise & Build | 100% → Projects | —          | —        |
  </Tab>
</Tabs>

***

## Step 6: Execute transfers

After the distribution is approved, make the actual money transfers, then record them in the system.

<Steps>
  <Step title="Execute transfers in your bank or mobile money platform">
    Transfer each amount according to the distribution. Note the reference number for each transfer.
  </Step>

  <Step title="Open the approved distribution batch">
    Go to **Financial Management → Distributions** and open the approved batch.
  </Step>

  <Step title="Mark each transfer as complete">
    Check the box next to a completed transfer, click **Mark as Transferred**, enter the bank reference number, and save. The status changes to "Executed" with the date.

    To record several at once, select multiple rows and click **Mark All as Transferred** — a window opens for entering reference numbers in bulk.
  </Step>
</Steps>

***

## Step 7: View reports

Go to **Financial Management → Reports**, select a report type, set your date range and other filters, then click **Generate Report**. Use **Export to Excel** to download.

| Report                         | What it shows                                  | Best for                         |
| ------------------------------ | ---------------------------------------------- | -------------------------------- |
| Reconciliation Summary         | Imported / matched / pending / disputed counts | Weekly progress check            |
| Distribution Report            | All distributions by category and status       | Understanding money flow         |
| Location Financial Summary     | What each branch received and sent             | Branch-level reporting           |
| Unmatched Transactions (Aging) | Pending items grouped by age                   | Following up on old transactions |

***

## Common weekly workflows

<Tabs>
  <Tab title="Central finance team">
    **Every Monday morning:**

    1. Download last week's Mobile Money and Bank statements
    2. Import both files (Mobile Money → Central MM account, Bank → Central Bank account)
    3. Reconcile: bulk-approve high-confidence matches, manually match the rest, mark anything unclear as disputed
    4. Calculate the distribution for last week
    5. Submit for leadership approval

    **Monday–Tuesday:**

    6. Leadership reviews and approves
    7. Execute transfers in bank/MM
    8. Mark transfers as completed in the system
    9. Generate the weekly summary report
  </Tab>

  <Tab title="Location finance">
    **Every Monday:**

    1. Count Sunday cash collections and create entries (or import if collected digitally)
    2. Import branch bank statement
    3. Reconcile to members (cash collections approved as "Cash Collection")
    4. Calculate branch distribution: 40% to Central, 30% to Welfare, 30% retained
    5. Execute the transfer to Central
    6. Mark as transferred in the system
  </Tab>
</Tabs>

### Recommended timing

| Day                  | Action                                         |
| -------------------- | ---------------------------------------------- |
| Monday morning       | Import statements and reconcile                |
| Monday afternoon     | Calculate distribution and submit for approval |
| Monday – Tuesday     | Leadership approval                            |
| Tuesday – Wednesday  | Execute transfers                              |
| Same day as transfer | Mark as transferred in system                  |

***

## Tips & best practices

### Phone number matching

The system normalizes phone numbers automatically. `+256772123456`, `0772123456`, and `772123456` all match the same contact. Spaces and dashes are ignored. Once a number is matched and approved, the system remembers it — future transactions from that number will score 95%+.

### Auto-match accuracy improves over time

| Period         | Typical auto-match rate |
| -------------- | ----------------------- |
| First week     | \~60%                   |
| After 1 month  | \~85%                   |
| After 3 months | 95%+                    |

**To improve accuracy:** always approve correct matches (teaches the system), add payment methods when matching manually, keep contact records up to date, update member locations regularly.

### When you can't identify a sender

1. Check with leadership — ask if anyone recognizes the number or name
2. Call the sender directly if possible
3. Mark as Disputed and add a note
4. Review disputed items every week
5. After 30 days unresolved, discuss a policy decision with leadership

### Service time offerings

Mobile money received on Sunday between 09:00 and 12:00 is auto-marked as "Offering" when the rule is active. You can still change this to "Tithe" during reconciliation if needed.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Transaction import failed">
    * **Check file format** — Ensure you have Date, Amount, and Name columns
    * **Check date format** — Use a consistent format throughout the file
    * **Check amounts** — Remove currency symbols (UGX) and commas
  </Accordion>

  <Accordion title="Cannot find a matching contact">
    * Try searching by first name only, then last name only
    * Verify the phone number is correct
    * If the contact doesn't exist, create them first via **People → Add Contact**, then return to reconciliation
  </Accordion>

  <Accordion title="Distribution totals don't match">
    * Refresh the page — sometimes the calculation needs a refresh
    * Check any manual edits you made to amounts
    * Delete and recreate the distribution batch to recalculate from scratch
  </Accordion>

  <Accordion title="Cannot approve a distribution">
    * Check your permissions — you may need approval rights
    * Check the batch status — it may already be approved
    * Contact your admin to request the approval permission
  </Accordion>

  <Accordion title="Wrong location attributed to a transaction">
    * Click **Edit** on the match
    * Change the location to the correct branch
    * The distribution will update automatically when you recalculate
  </Accordion>

  <Accordion title="Cannot approve — batch already approved by someone else">
    * **Refresh the page** — a colleague may have approved it while you were reviewing
    * Check the **Matched** tab — the transaction is likely already there
    * Move on to the next pending item
  </Accordion>
</AccordionGroup>

***

## Permissions

| Role                    | Access                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Central Finance**     | Import (all accounts), reconcile (all), calculate and view distributions, execute transfers, view all reports |
| **Location Finance**    | Import (own account only), reconcile (own location only), view own distributions and reports                  |
| **Location Leadership** | View and approve distributions (own location), view reports                                                   |
| **Senior Leadership**   | Approve all distributions, view all reports, manage category rules                                            |