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

# Payment rules

> Match incoming payments to the right lease and decide what allocation settles first.

**Admin → Payment Rules → `/payment-rules`** · Allocation rules → `/payment-allocation-rules`

Payment rules do two jobs:

1. **Matching** — turn a bank or mobile-money reference into the right lease.
2. **Allocation order** — decide which outstanding invoice a payment settles first.

Both are what let money arrive and be applied without a person reading each reference.

## Matching rules

| Field                             | Purpose                                                   |
| --------------------------------- | --------------------------------------------------------- |
| **Rule name**                     | What the rule is for.                                     |
| **Match type**                    | How the incoming reference is compared.                   |
| **Match value**                   | What is matched against.                                  |
| **Replace value**                 | A normalisation applied to the reference before matching. |
| **Reference**                     | The reference pattern involved.                           |
| **Bank account**                  | The account the rule applies to.                          |
| **Branch / block / unit / lease** | The scope the rule applies to.                            |
| **Priority**                      | The order rules are evaluated in.                         |
| **Start / End**                   | When the rule is effective.                               |
| **Enabled / Active**              | Whether it is in force.                                   |
| **Admin only**                    | Whether only administrators may edit it.                  |

### How matching works in practice

A tenant paying by mobile money types an account reference. If they type it exactly as instructed,
matching is trivial. In reality they type it with spaces, with the unit name instead of the lease
code, or with a previous tenant's reference.

Matching rules absorb that variation:

* **Replace value** normalises the reference — stripping separators, correcting a known prefix.
* **Priority** decides which rule wins when more than one could match.
* **Scope** limits a rule to a bank account, branch, block, unit or lease, so a fix for one estate
  does not misroute another's payments.

<Steps>
  <Step title="Publish one reference format and use it everywhere">
    On invoices, in reminders, on the notice board. Most unmatched payments are payers using a
    format nobody told them.
  </Step>

  <Step title="Watch what actually arrives">
    Review unmatched receipts weekly for a month after go-live. The patterns repeat.
  </Step>

  <Step title="Write narrow rules first">
    A broad rule with high priority can capture payments it should not.
  </Step>

  <Step title="Date-bound corrective rules">
    A rule fixing a legacy reference format should have an end date, not live forever.
  </Step>
</Steps>

<Warning>
  A wrong matching rule attributes money to the wrong tenant. That produces an arrears case against
  someone who paid, and a credit for someone who did not. Test a new rule against known references
  before enabling it.
</Warning>

## Allocation rules

Allocation rules decide the **order** in which a matched payment settles outstanding items — the
**default allocation** behaviour, plus rules scoped by service type or context.

Typical orderings:

| Order                        | Rationale                                                  |
| ---------------------------- | ---------------------------------------------------------- |
| **Oldest first**             | Reduces aging and write-off risk. The usual default.       |
| **Rent before utilities**    | Protects the core contractual income.                      |
| **Charges before penalties** | Avoids fees consuming a payment while principal debt ages. |
| **Specific invoice first**   | Where the payer identified what they were paying.          |

Rules can be scoped by service type, bank account and the position in the hierarchy, so a scheme
with different priorities does not force a change everywhere.

<Note>
  Allocation rules drive the [allocation engine](/guides/allocations), which is preview-first: you
  can see what a rule set *would* do before it does it, and revert a run that did the wrong thing.
</Note>

## Testing a rule change

<Steps>
  <Step title="Run an allocation preview">
    Not an execute. Read what would be allocated and what would be skipped.
  </Step>

  <Step title="Check a handful of leases by hand">
    Especially ones with mixed debt — rent, utilities and a penalty.
  </Step>

  <Step title="Execute, then check the run log">
    Allocated, skipped and error counts, with reasons.
  </Step>

  <Step title="Revert if it is wrong">
    Reversal is a first-class operation. Use it rather than unpicking allocations by hand.
  </Step>
</Steps>

## Common problems

| Symptom                             | Cause                                                                             |
| ----------------------------------- | --------------------------------------------------------------------------------- |
| Payments arriving unmatched         | No rule covers the reference format payers actually use.                          |
| Payment matched to the wrong lease  | A broad rule with high priority. Narrow the scope.                                |
| Penalties being settled before rent | Allocation order. Reorder so principal debt clears first.                         |
| Engine allocates nothing            | No matching outstanding invoices in scope — read the skip reasons in the run log. |

## Next steps

<Columns cols={2}>
  <Card title="Allocations" icon="link" href="/guides/allocations">
    The engine these rules drive.
  </Card>

  <Card title="Bank accounts" icon="building-columns" href="/guides/bank-accounts">
    Paybills and reference separators.
  </Card>
</Columns>