Failed, pending, and duplicate payments

Resolve uncertain attempts, failed captures, duplicates, mismatched references and handover exceptions safely.

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 and channel evidence
• Search access across attempts and payments
• Approved exception ownership and escalation path

Key definitions and boundaries

A pending or processing attempt is not a failure and not a Payment. A failed or expired attempt preserves why the channel did not complete. A duplicate can exist at attempt, Payment, allocation or receipt level; each needs different handling. Idempotency keys and request fingerprints prevent repeat economic effects, while search by payer, student, amount, currency, date and external reference detects duplicates that crossed channels or operator sessions.

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.

• payment_attempt:list
• payment_attempt:read
• payment_attempt:cancel
• payment_attempt:confirm
• financial_payment:list
• financial_payment:read
• financial_payment:search
• financial_payment:delete
• financial_payment:verify
• financial_receipt:read
• finance_control:readiness

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. Freeze the economic effect

When status is uncertain, stop new allocation, receipt, refund and manual recapture. Record the case owner and reference. Do not “test” by creating another Payment. Search both attempts and Payments because a callback may have materialised funds even when the original screen timed out.

2. Build the identity fingerprint

Compare school, student, invoice allocations, amount, currency, method, provider, payer, external reference, time window, idempotency key and payment/receipt numbers. Similar amounts are not sufficient. The same payer can legitimately make two payments; the same provider reference should normally not fund two records.

3. Resolve pending and processing attempts

Use provider status checks only through authorised workspaces. Wait according to channel timeout and expiry rules. Cancel only when the contract allows and after proving no succeeded callback/Payment exists. If status becomes succeeded, require the linked Payment. If it becomes failed or expired, retain failure code/reason and create a new attempt with a new business idempotency decision only when retry is approved.

4. Resolve duplicates at the correct layer

• Duplicate attempt with no Payment: cancel/expire the redundant attempt.
• Two attempts but one Payment: preserve both attempts and link the economic result correctly.
• Two Payments for one receipt of funds: freeze allocations/receipts and initiate controlled reversal/refund for the duplicate.
• One Payment allocated twice or over-allocated: correct through allocation controls.
• Duplicate receipt only: issue/cancel according to receipt duplicate rules without changing funds.

Deleting a non-reconciled Payment may be technically available, but deletion is not the default duplicate remedy. Use it only under the approved record-removal policy and never after reconciliation.

5. Close with a reproducible exception pack

Record the timeline, searches, provider evidence, decision, actors, identifiers, financial effect and downstream handoffs. Confirm invoice balances, student summary, receipt state, cashier totals and provider/bank queues. The case is not closed merely because the user can no longer see the duplicate row.

Worked Mupfure scenario

A PayNow attempt remains processing after the payer reports success. A cashier nearly records cash as a workaround. Support stops the recapture, searches by payer phone, USD 180, student and timestamp, and finds a succeeded callback with a linked Payment. The Payment is unallocated and has no receipt. The team allocates and receipts that Payment, then cancels a second unused attempt. No duplicate Payment is created, and the exception pack records the delayed callback and all identifiers.

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
Operator retries without search	Stop and perform cross-layer duplicate search before further mutation.
Pending treated as failed	Use status/timeout evidence; premature retries create duplicates.
Succeeded attempt has no Payment	Escalate materialisation failure; do not manually reduce invoice.
Duplicate Payment already receipted	Freeze both trails and process an approved correction; do not delete casually.
Exception closed after hiding row	Reopen until balances, cash/provider queues and audit evidence reconcile.

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. Diagnose a processing attempt after a browser timeout.
2. Build a duplicate fingerprint and decide which layer is duplicated.
3. Produce an exception pack that another reviewer can reproduce without verbal context.

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.