Record a payment

Capture an incoming payment with the correct student, school, method, amount, currency and channel 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

• Collection lifecycle
• A selected school and verified invoice
• Approved payment method/provider configuration

Key definitions and boundaries

A Payment requires studentId, schoolId, paymentDate, paymentMethod, amount and currency. Payment numbers are generated by the service. Channel evidence varies: mobile-money methods require provider and number; cheque requires cheque number; card/POS requires exactly four card digits; bank methods require a usable external reference under school policy. Payment source identifies who funded the payment and can be student, parent, guardian, sponsor, scholarship, government, NGO, corporate or other.

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:create
• financial_payment:list
• financial_payment:read
• financial_payment:update
• financial_payment:verify
• financial_payment:search
• financial_invoice:list
• financial_invoice: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. Establish identity and amount

Search the student in the active school. Open the invoice and confirm invoice number, currency, due amount and any discount application. Never key a payment from a guardian screenshot alone. Confirm payer name and relationship where available. The payer may differ from the student, but the credited student and school must be unambiguous.

2. Select the correct method

Use the canonical method rather than a local nickname. card normalises to credit_card, online to online_payment, and pos to swipe, but operators should select the explicit product option. For bank transfer, wire, RTGS, ZIPIT and direct debit, record a bank reference. For EcoCash, OneMoney, Telecash, InnBucks or generic mobile money, record provider, mobile number and transaction reference. For debit card, credit card or swipe, capture card last four and terminal evidence in metadata without storing full card data.

3. Submit once and read back

Use one intentional submission. Where idempotency is available, preserve the key across a retry. After save, read the Payment and compare every critical field to the source evidence. Payment creation defaults may be completed while isVerified and isReconciled are false. Verification uses a separate action and records actor, timestamp and notes.

4. Restrict edits

Edit only permissible descriptive fields while the Payment is not reconciled or refunded. The application deliberately excludes student, school, invoice and receipt identity from ordinary update payloads. A wrong student or school is not a cosmetic edit; stop and use the approved correction process. Deleting a reconciled Payment is forbidden, and deleting evidence should never substitute for a reversal or refund.

Worked Mupfure scenario

A parent presents a CBZ transfer for USD 420. The bursar searches the student, confirms an invoice has USD 420 outstanding, selects bank_transfer, records the payer and CBZ reference, and creates the Payment once. The returned record is completed, unverified, unallocated and unreconciled. A second authorised user checks the reference against available bank evidence and invokes verification. Allocation and receipt follow as separate actions.

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
Zero or negative amount	The service rejects it. Reconfirm the source document and never use a negative Payment as a refund.
Mobile-money details missing	Do not relabel the transaction as cash. Capture the required provider, number and reference.
Card last four missing	Hold the capture and recover terminal evidence; full card numbers must not be stored.
Wrong student selected	Do not edit identity fields or allocate. Escalate for controlled cancellation/reversal and recapture.
Double-click or timeout	Search by reference, student, amount and date before retrying; reuse the idempotency key where supported.

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. Build a capture checklist for cash, bank transfer, mobile money and POS.
2. Explain why payment status completed does not imply verified or reconciled.
3. Identify which fields must never be “fixed” by an ordinary update after a wrong-student capture.

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.