Mobile money, card, and gateway workflows

Operate asynchronous providers through attempts, callbacks, status checks, saved payments and provider-specific controls.

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

• Active provider with credentials
• Approved return/cancel URLs and channel configuration
• A verified invoice allocation plan

Key definitions and boundaries

Payment Attempts exist before Payment records. Supported generic attempt methods include Stripe, mobile money, bank transfer, card, wallet and other. Provider workspaces include EcoCash/OneMoney/Telecash, PayNow, InnBucks and Stripe. An attempt can expose a redirect URL, gateway session, provider reference, expiry and failure reason. Only a succeeded attempt linked to a saved Payment completes the recording step.

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:view
• payment_attempt:list
• payment_attempt:read
• payment_attempt:create
• payment_attempt:cancel
• payment_attempt:confirm
• payment_attempt:delete
• stripe_gateway:read
• stripe_gateway:create_checkout
• stripe_gateway:create_payment_intent
• stripe_gateway:create_refund
• financial_payment: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. Prove provider readiness

Check that the provider record belongs to the active school, is active and has credentials. Provider dashboards can show placeholder data when readiness fails. Never use those values for collections reporting. Route permissions differ: generic attempts use attempt abilities; PayNow currently uses a route-specific delete ability for cancellation, while generic attempts use cancel; Stripe uses its own gateway abilities. Document and test the exact route contract rather than assuming aliases are interchangeable.

2. Initiate with conservation and idempotency

Select one or more invoice allocations whose total matches the intended attempt amount. Provide payer details and a fresh idempotency key. Stripe/card requires success and cancel URLs. Mobile money requires provider and mobile number. Store no secrets or full card data in metadata. Displaying a checkout URL, client secret, QR code, USSD string or mobile prompt means only that initiation succeeded.

3. Observe the provider lifecycle

Use status checks and callbacks to move from pending/processing to a terminal state. Do not manually confirm merely because a payer says the account was debited. Manual confirmation requires authorised independent evidence. Preserve failure code/reason and raw-response reference without exposing sensitive payloads to general users.

4. Require a saved Payment

After succeeded, verify the paymentId and open the Payment. Check amount, currency, student, method, gateway reference and allocations. If the provider says success but no Payment exists, hold the case as a materialisation exception. Do not issue a receipt or reduce the invoice manually.

5. Treat provider refunds carefully

Stripe can submit a provider refund, but provider acceptance is not the whole finance correction. Verify Payment refund evidence, allocation/receivable effects, receipt treatment and downstream posting/reconciliation handoff. The current Stripe page's displayed refund aggregate is not authoritative where the UI does not load actual refund totals.

Worked Mupfure scenario

A guardian chooses PayNow mobile money for USD 250. The operator initiates one attempt with the invoice allocation and payer phone. The attempt remains processing while the payer authorises the prompt. A status refresh later returns succeeded and a Payment ID. The bursar opens that Payment, confirms the PayNow reference and amount, verifies the allocation and issues a receipt. A second processing attempt with the same business intent is cancelled only after duplicate review; no second Payment is created.

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
Checkout link created but unpaid	Keep the attempt pending; do not create a manual Payment.
Provider warning shows placeholder rows	Exclude them from every operational total.
Success callback but no Payment	Escalate materialisation failure and preserve callback/request IDs.
Manual confirm based only on payer screenshot	Reject the confirmation until independent channel evidence exists.
Provider refund shown as submitted	Continue verification until Payment, allocation, receipt and accounting evidence agree.

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. Define the minimum evidence for provider readiness and attempt success.
2. Compare PayNow cancellation permission with generic Payment Attempt cancellation.
3. Explain why a Stripe checkout session and a Payment are different records.

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.