Payment Workflow — Option B

School policy (non-negotiable)

• A fee is officially paid only when status is APPROVED and a receipt exists in the system.
• Parents must submit a claim within 7 calendar days of payment (configurable per school).
• Claims older than the policy window move to EXPIRED unless bursar extends.
• Balance on the parent portal shows outstanding until approval — not when MoMo is sent.

End-to-end flow

Direct in-office recording (bursar enters while parent waits) remains supported and skips the claim queue — it creates an APPROVED payment immediately with source BURSAR_DIRECT.

Payment claim statuses

Payment record status (after approval)

Separate from claim status — the financial payments table:

• CONFIRMED — approved claim or direct bursar entry
• VOIDED — director/bursar void with mandatory reason (audit logged)
• REFUNDED — partial or full refund linked to original payment

Parent claim form — fields

Bursar verification queue

Bursar dashboard shows filters: Pending, Under review, Needs info, Duplicates, All today.

On approve, bursar must:

1. Confirm amount matches MoMo/bank/cash record
2. Select invoice line(s) to apply payment (auto-suggest oldest open invoice)
3. Optionally adjust approved amount (with reason if different from claim)
4. Click Approve & issue receipt — atomic transaction

System generates receipt number, publishes PaymentReceived, posts to finance-service ledger (Phase 2 basic), notifies parent.

Edge cases & business rules

Domain events & notifications

API endpoints (fee-service via gateway)

# Parent portal
GET    /api/v1/portal/fee-accounts/{studentId}          # balance, open invoices
POST   /api/v1/portal/payment-claims                    # submit claim
GET    /api/v1/portal/payment-claims                  # list own claims
GET    /api/v1/portal/payment-claims/{id}             # detail + status history
PUT    /api/v1/portal/payment-claims/{id}             # update when NEEDS_INFO
DELETE /api/v1/portal/payment-claims/{id}             # cancel if PENDING only
POST   /api/v1/portal/payment-claims/{id}/attachments # proof upload

# Bursar / admin
GET    /api/v1/admin/payment-claims?status=&campusId= # verification queue
GET    /api/v1/admin/payment-claims/{id}              # full detail + audit
POST   /api/v1/admin/payment-claims/{id}/start-review   # → UNDER_REVIEW
POST   /api/v1/admin/payment-claims/{id}/needs-info   # body: { message }
POST   /api/v1/admin/payment-claims/{id}/approve        # body: { amount, invoiceIds[] }
POST   /api/v1/admin/payment-claims/{id}/reject         # body: { reason }
POST   /api/v1/admin/payments                           # direct entry (BURSAR_DIRECT)
POST   /api/v1/admin/payments/{id}/void                 # void with reason

Data model (fee-service DB)

payment_claims
  id UUID PK
  organization_id, campus_id
  student_id, guardian_id
  invoice_id (nullable if multi-invoice apply)
  amount_claimed DECIMAL(14,2)
  amount_approved DECIMAL(14,2) NULL
  currency CHAR(3) DEFAULT 'UGX'
  payment_method ENUM
  transaction_id VARCHAR(128) NULL
  payer_phone VARCHAR(20) NULL
  agent_number VARCHAR(32) NULL
  bank_name VARCHAR(64) NULL
  payment_date DATE
  notes TEXT
  proof_file_id UUID NULL → file-service
  status ENUM (see statuses above)
  duplicate_of_claim_id UUID NULL
  reviewed_by UUID NULL
  reviewed_at TIMESTAMPTZ NULL
  rejection_reason TEXT NULL
  version INT DEFAULT 1          -- optimistic lock
  created_at, updated_at

payment_claim_status_history
  id, claim_id, from_status, to_status, actor_id, note, created_at

payments
  id, organization_id, campus_id, student_id
  claim_id UUID NULL             -- null if BURSAR_DIRECT
  source ENUM: PARENT_CLAIM | BURSAR_DIRECT
  amount, payment_method, transaction_id
  receipt_number VARCHAR UNIQUE
  status CONFIRMED | VOIDED | REFUNDED
  void_reason, voided_by, voided_at
  created_at

payment_allocations
  payment_id, invoice_id, amount_applied

fee_invoices / fee_invoice_lines  -- existing invoice model
fee_accounts                      -- per-student running balance