Admin → Payment Rules → /payment-rules · Allocation rules → /payment-allocation-rules
Payment rules do two jobs:
- Matching — turn a bank or mobile-money reference into the right lease.
- 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.
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.
Watch what actually arrives
Review unmatched receipts weekly for a month after go-live. The patterns repeat.
Write narrow rules first
A broad rule with high priority can capture payments it should not.
Date-bound corrective rules
A rule fixing a legacy reference format should have an end date, not live forever.
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.
Testing a rule change
Run an allocation preview
Not an execute. Read what would be allocated and what would be skipped.
Check a handful of leases by hand
Especially ones with mixed debt — rent, utilities and a penalty.
Execute, then check the run log
Allocated, skipped and error counts, with reasons.
Revert if it is wrong
Reversal is a first-class operation. Use it rather than unpicking allocations by hand.
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. |