Collection lifecycle

Understand how attempts, payments, verification, allocation, receipts, cash controls and downstream evidence fit together.

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

• P1 object and permission model
• P2 payment providers, currencies and approvals
• P3 invoices and student balances

Key definitions and boundaries

• Payment attempt: a pre-Payment lifecycle used for asynchronous channels. Its verified states are pending, processing, succeeded, failed, expired and cancelled.
• Payment: the Makronexus record of incoming funds. Payment status, verification status, allocation status and reconciliation status are separate dimensions.
• Allocation: the application of payment value to one or more invoices. Unallocated value remains payment value but does not settle a named invoice.
• Receipt: numbered evidence issued from a saved payment, with its own approval, delivery, cancellation and duplicate history.
• Cashier session, cash-up, custody lot and deposit batch: operational control records for physical cash authority, count, handoff and deposit lineage.
• Reconciliation: comparison to external bank/provider evidence. P4 records prerequisites and handoff evidence; the full process belongs to P6.

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:list
• financial_payment:read
• financial_payment:statistics
• payment_attempt:list
• payment_attempt:read
• financial_receipt:list
• financial_receipt:read
• student_financial_summary:read

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. Start from the obligation

Open the student's verified invoice or front-desk list and use amountOutstanding as the collection ceiling unless an approved overpayment or student-credit procedure applies. Confirm any current discount before taking money. A stale screen can cause overcollection, so refresh after another cashier, provider callback or credit-note action.

2. Choose the record path

Use a direct Payment capture for controlled manual channels such as cash or a verified bank deposit. Use Payment Attempts for asynchronous card, mobile-money, PayNow, Stripe or reference-based flows. An attempt that only has a redirect URL or provider reference is not yet a Payment. Require succeeded plus the resulting paymentId or saved Payment record before treating funds as recorded.

3. Prove the Payment

Read the saved Payment by ID or payment number. Check school, student, amount, currency, method, payment date, payer, status and channel reference. Then check the independent verification and allocation dimensions. The default creation behaviour may produce a completed payment that is not yet verified or reconciled; therefore completed alone is not a universal cash-in-bank assertion.

4. Complete the controlled handoffs

Allocate the value, issue the receipt, and route physical cash or external-channel evidence to its control workspace. A receipt can be approved and sent while bank reconciliation is still outstanding. Conversely, a provider attempt can succeed before a receipt is issued. Keep the timeline explicit.

Worked Mupfure scenario

A guardian pays USD 500 toward two invoices: USD 350 tuition and USD 150 transport. The cashier confirms both outstanding amounts, captures one Payment, allocates two legs, verifies that allocated value is USD 500 and unallocated value is zero, then issues one official receipt linked to the Payment and both invoices. The receipt delivery is recorded separately. If the channel is cash, the amount also belongs to the active cashier session and later denomination cash-up; if it is bank transfer, the reference waits for external matching in P6.

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
Attempt shown as processing	Do not create a duplicate Payment. Refresh the attempt, preserve its idempotency key and escalate only after the provider timeout procedure.
Payment is completed but unverified	Treat it as recorded but awaiting verification; do not claim independently confirmed funds.
Allocated amount exceeds payment	Stop and correct the allocation request. Over-allocation is an exception, not a harmless display issue.
Receipt exists without a traceable Payment	Cancel or hold the receipt according to policy and investigate the broken evidence chain.
Cash payment has no open cashier session	Do not retrofit another operator’s session. Escalate as an unauthorised collection exception.

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. Explain the difference between a succeeded Payment Attempt and a completed Payment.
2. For a payment that is completed, unverified, fully allocated and unreconciled, state exactly what is and is not proven.
3. Trace one Mupfure payment through Payment, allocation, receipt and channel handover identifiers.

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.