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

# Refunds

> Return money to a payer with the right guards — over-refund protection, bank account control, and a full ledger.

Refunds are money going back out to someone who paid you: an overpayment, a cancelled booking, a
returned deposit, or a payment received in error.

Refunds are a **ledger in their own right**, not an edit to the original payment. The payment stays
exactly as it was received; the refund is a separate, auditable event against it.

## Where refunds live

| Surface                      | What it gives you                                                 |
| ---------------------------- | ----------------------------------------------------------------- |
| **Payment detail → Refunds** | Raise and manage refunds against a specific payment.              |
| **Refunds ledger**           | Every refund across the branch, for reporting and reconciliation. |

## Refund types

| Type        | Meaning                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Payment** | Returning money received as a normal payment.                                                                                         |
| **Deposit** | Returning a security deposit. See [Security deposits](/guides/security-deposits) for the deduction workflow that usually precedes it. |

## Raising a refund

<Steps>
  <Step title="Open the payment">
    Refunds are always anchored to the payment being returned, so the trail from money-in to
    money-out is unbroken.
  </Step>

  <Step title="Enter the refund">
    Refund amount, refund date, the bank account the money is paid **from**, a reason, and a
    reference.
  </Step>

  <Step title="Save">
    Server-side guards run before anything is written.
  </Step>
</Steps>

### The guards

| Guard                     | What it prevents                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| **Over-refund**           | Refunding more than the payment's available amount, across all refunds already raised against it. |
| **Bank account required** | A refund with no source account, which cannot be reconciled or posted.                            |
| **Reason required**       | An unexplained outflow.                                                                           |

These checks run on the server, not just in the form, so they hold for imports and integrations
too.

## Reading the refunds ledger

| Column                          | Meaning                                                    |
| ------------------------------- | ---------------------------------------------------------- |
| **Title**                       | The refund description.                                    |
| **Type**                        | Payment or deposit.                                        |
| **Refund Amount**               | Amount returned.                                           |
| **Refund Date**                 | When it was returned.                                      |
| **Reason**                      | Why.                                                       |
| **Reference #**                 | The outbound reference (bank or mobile-money transaction). |
| **Payment Amount**              | The original payment's amount.                             |
| **Payment Confirmation #**      | The original inbound reference.                            |
| **Invoice No / Invoice Amount** | The invoice involved, where the payment was allocated.     |
| **Paid From Account**           | The bank account the refund was paid from.                 |

## Refunds, allocations and balances

The order of operations matters:

* If the payment was **already allocated** to an invoice, reverse the allocation first. Refunding
  allocated money leaves an invoice marked paid with the cash gone.
* If the payment is **unallocated**, refunding it simply reduces the lease's wallet.
* A refund never edits the original payment record. Available amount on the payment reduces because
  the refund consumed it.

<Warning>
  Do not "refund" by deleting a payment. Deleting removes the receipt from the ledger and from bank
  reconciliation; the money still left your account. Raise a refund.
</Warning>

## Deposit refunds

A security-deposit refund normally follows a deduction process — damages, unpaid rent, cleaning —
so the refunded figure is the deposit less agreed deductions. Run the deduction workflow in
[Security deposits](/guides/security-deposits) first, then refund the balance.

## Permissions

Refunds carry their own permission set: **view**, **create**, **edit**, **delete**, **allocate**
and **reverse**. Most organisations grant create to finance staff and reserve reverse for a
supervisor.

## Reconciling refunds

<Steps>
  <Step title="Filter the ledger by bank account and date">
    Match one account and one statement period at a time.
  </Step>

  <Step title="Match on reference">
    The outbound reference should appear on the bank statement.
  </Step>

  <Step title="Check against expenses">
    A refund is not an expense. If a refund also appears as an expense payment, one of the two is a
    duplicate.
  </Step>
</Steps>

## Common problems

| Symptom                                    | Cause                                                                                                                              |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Refund rejected as over-refund             | Earlier refunds already consumed the available amount, or the payment is fully allocated.                                          |
| Refund saved but bank shows nothing        | The refund was recorded in the system but never actually paid out. The ledger records intent; someone still has to move the money. |
| Invoice shows paid but tenant was refunded | The allocation was not reversed before the refund.                                                                                 |