Ownership plans → Boma Yangu Reports → /tps/allocation-reports
Payments collected against a Boma Yangu tenant purchase scheme have to be reported back to the Boma Yangu API: the scheme's own records need to know how each payment was split between principal, interest and other components. That reporting is automatic — this console is where you confirm it actually happened.
How a report is produced
A payment lands on a Boma Yangu account
The pay-to account identifies it as in scope.
Allocation runs
The payment is allocated across the contract's schedule — principal, interest, and any other component. See Allocations.
A report is queued
The resulting split becomes an allocation report addressed to the Boma Yangu API.
The queue is drained
A background job submits queued reports and records the outcome against each one.
Reading a report's status
| Status | Meaning |
|---|---|
| Queued | Created and waiting for the next submission pass. |
| Processing | Currently being submitted. |
| Sent | Delivered to the API; no acknowledgement yet. |
| Acknowledged | The API confirmed receipt. This is the terminal success state. |
| Failed | Submission failed. Retryable. |
| Dead | Retries exhausted. Needs investigation before it will move again. |
Only acknowledged means the scheme's records agree with yours. Sent without an acknowledgement for an extended period is worth chasing — it usually points at the far side, not at Nyumba Zetu.
Working the queue
Filter by status and start from the failures.
Read the failure reason on the report
Open the report to see what the API returned. Most failures are data, not transport — a contract reference the scheme does not recognise, or an amount split it rejects.
Fix the cause, not the report
If the allocation itself was wrong, correct it in Allocations first — retrying an incorrect report just re-sends the same wrong figures.
Retry
Failed reports carry a Retry action. It resubmits the report as it stands.
Escalate dead reports
A dead report has exhausted its retries. Treat it as a data or integration problem, not a transient one.
Shadow mode
The feature can run in shadow mode: reports are produced and recorded exactly as they would be, but nothing is submitted. This is how the integration is validated against real payments before it is switched on for an organisation. In shadow mode the console is still the right place to look — the reports and their computed splits are real, only the delivery is withheld.
Common problems
| Symptom | Cause |
|---|---|
| A payment has no report | It was not received into a Boma Yangu collection account. |
| Reports stay queued | The submission job is not running — check Scheduled tasks. |
| Everything is queued and nothing sends | Shadow mode is still on for the organisation. |
| Repeated failures on one contract | A reference mismatch between the two systems, not a transport fault. |
| Report figures look wrong | The underlying allocation is wrong. Fix the allocation, then retry. |
| Sent but never acknowledged | Awaiting the far side; chase with the scheme rather than retrying repeatedly. |