Allocate and reallocate payments

Apply payment value to invoices, preserve unallocated credit and control multi-currency settlement evidence.

Product-truth rule

Makronexus keeps several records deliberately separate. A payer's intention, a provider session, a Payment record, an invoice allocation, a receipt, a cashier count, a bank deposit and a reconciliation match answer different questions. Never collapse them into one green badge. A safe operator follows the evidence chain and names the exact record that proves each claim.

At Mupfure Learning Academy, use the authenticated tenant and selected school on every collection action. Confirm the student, invoice, currency, amount, channel and business date before mutation. Use generated identifiers and audit fields after mutation; do not rely on a toast, copied reference or printed page as the sole proof. Where a provider is missing, inactive or lacks credentials, provider workspaces may show warnings or placeholder data. Placeholder rows are not transactions and must never enter a handover, receipt or reconciliation total.

Learning outcomes

By the end of this chapter, you can:

• explain the records and lifecycle dimensions used by this workflow;
• choose the correct workspace and exact permission for each action;
• perform the workflow without treating a UI success message as financial proof;
• identify exceptions before they alter invoices, cash, receipts or external evidence;
• assemble an audit trail another reviewer can reproduce.

Prerequisites

• A saved Payment
• Current invoice outstanding amounts
• Approved FX and settlement configuration for cross-currency cases

Key definitions and boundaries

Allocation legs contain invoice ID, amount and currency. The standard allocation action recomputes allocated amount, unallocated amount and allocation status. Valid statuses are unallocated, partially_allocated, fully_allocated and over_allocated. Cross-currency advanced allocation is a different governed operation: it requires settlement account, rates, rate definitions, source/timestamp/effective date/reference, reason and idempotency, and returns posted batch, leg and journal evidence.

Roles and exact permissions

Use only abilities assigned for the active tenant and school. Backend enforcement remains authoritative, and route aliases do not replace endpoint-specific permissions.

• financial_payment:allocate
• financial_payment:read
• financial_payment:verify
• financial_invoice:list
• financial_invoice:read
• student_financial_summary:read
• finance_control:read
• finance_control:approve

A role that can view a record does not automatically have authority to create, confirm, verify, allocate, refund, approve or delete it. Apply segregation of duties for independent monetary decisions.

Workflow map

Guided procedure

1. Re-read the Payment and invoices

Confirm amount, currency, student and current allocation state. Refresh every target invoice immediately before allocation. Do not allocate against cancelled, wrong-student or wrong-school invoices. The sum of proposed legs must be positive and must not exceed available payment value in the applicable contract.

2. Decide the remainder treatment

A partial allocation is legitimate when the payer has not instructed use of the full value or when a valid target invoice is not yet available. Record allocation notes and leave the remainder visible. Do not force a random invoice merely to obtain fully_allocated. An overpayment may become student credit under the active policy; document the handoff rather than inventing a negative invoice.

3. Submit a complete allocation set

The Payment allocation endpoint accepts one or more invoice allocations. After mutation, verify each leg, allocated total, unallocated total and resulting invoice paid/outstanding amounts. Then compare the student financial summary. If the summary is stale, use the authorised recalculation path from P3 and retain the recalculation timestamp.

4. Control reallocation

Reallocation means changing economic application, not editing a label. Preserve before-state evidence, reason, requester and approver. Do not silently overwrite previously receipted or reconciled allocation history. Where the active product exposes only a new allocation action, use the approved corrective workflow and audit record rather than claiming a universal “move” button.

5. Treat cross-currency allocation as posting-grade

Advanced allocation requires a live connection and commits allocation, receivable settlement, payment verification and journal posting atomically. Verify batch ID, payment ID, settlement account, tender and functional totals, rate snapshot/request, idempotency, leg journal IDs, invoice before/after values and realised FX result. This is not the ordinary cashier allocation path.

Worked Mupfure scenario

A guardian pays USD 700. Invoice A is USD 500 and Invoice B is USD 150. The operator allocates USD 650 and leaves USD 50 unallocated pending written instruction. The Payment becomes partially allocated, both invoices show their correct new balances, and the student summary exposes the residual credit. Later allocation of the USD 50 requires refreshed invoice evidence and a recorded reason; the earlier receipt and allocation history remain traceable.

Control standard

Apply the following control standard to every collection channel:

1. Identify the payer, student, school, currency and obligation independently.
2. Authorise the operator through the exact route permission, not only menu visibility.
3. Capture the channel evidence required for that method, such as a bank reference, mobile number, card last four digits or cash-session identity.
4. Verify the resulting lifecycle state and immutable identifiers after the request completes.
5. Allocate only against valid invoices and prove that allocated plus unallocated value equals the payment amount.
6. Issue evidence only from the saved Payment and its allocation context.
7. Handover cash, provider and exception evidence to the correct downstream workspace without pretending that P5 posting or P6 reconciliation is complete.

Maker and reviewer should be different people for verification, refunds, cash-up approval, custody acceptance, deposit dispatch and any manual provider confirmation. When staffing makes this impossible, record the approved exception and obtain retrospective review under school policy. Never share credentials, edit gateway payloads, reuse another operator's session, or delete evidence merely to remove a discrepancy.

Failure modes

Failure or warning	Required response
Allocation total exceeds payment	Reject the request and recalculate from the saved Payment, not a spreadsheet subtotal.
Invoice balance changed during entry	Refresh and rebuild the allocation; do not rely on the stale amount.
Wrong-currency invoice	Use the governed advanced allocation path only when approved rate and settlement evidence exist.
Unallocated amount hidden	Stop receipt/handover review until the remainder is explicitly explained.
Historical allocation overwritten	Restore traceability through a controlled correction and reviewer evidence.

Verification checklist

Before declaring this workflow complete, verify:

• the tenant, school, student and operator identities are correct;
• amount, currency, business/payment date and channel agree with source evidence;
• every attempt, Payment, allocation, receipt or control record has its own saved identifier;
• lifecycle states are read from the saved records after mutation;
• allocated and unallocated values conserve the Payment amount;
• duplicate and idempotency searches were completed where uncertainty existed;
• approval, verification and exception notes identify actors and timestamps;
• cash/provider/bank evidence was handed to the correct downstream workspace;
• no P5 posting or P6 reconciliation completion is claimed without those records.

Practice and knowledge check

1. Allocate a sample Payment to three invoices and prove the conservation equation.
2. Explain when an unallocated remainder is safer than forcing full allocation.
3. List the extra evidence required for cross-currency advanced allocation.

Record your answers with the Payment/attempt/receipt/control IDs used. A reviewer must be able to reproduce the result from Makronexus without relying on screenshots alone.