# PAR-08 through PAR-11: Parent Finance — Figma Production Specs --- ## 1. PAYMENT FLOW ARCHITECTURE ### Complete Payment Journey ``` PAR-01 (Dashboard) │ ├── "Pay Now" on KPI card ├── "Pay Now" on Invoice Quick-Pay widget │ ▼ PAR-08 (Invoices List) │ Click "Pay Now" on invoice card ▼ PAR-09 (Invoice Detail) │ Review line items, amounts │ Click "Pay Now" ▼ PAR-10 (Payment Flow) │ Select payment method │ Enter payment details │ Submit payment │ ├── Paystack inline popup (Card) │ └── No redirect — modal overlay │ ├── Paystack Mobile Money │ └── Send request → phone confirmation → polling │ ├── Paystack Bank Transfer │ └── Virtual account details → user confirms │ └── Paystack USSD └── USSD code displayed → user dials → polling │ ▼ PAR-11 (Receipt Download) │ ├── Auto-email receipt ├── Download PDF └── Return to dashboard ``` --- ## 2. INVOICE BUSINESS RULES ### Invoice Generation Rules | Rule | Description | |------|-------------| | Primary guardian | Invoice always FK to primary guardian's user_id | | Invoice number | Format: INV-YYYY-NNNN (auto-generated, sequential) | | Currency | GHS (Ghana Cedis) — default | | Status flow | draft → sent → partially_paid → paid / overdue / cancelled / refunded | | Due date | Set per fee_structure, configurable | | Line items | One per fee_category, with quantity, unit price, discount | | Discount | Per-line and per-invoice level | ### Invoice Status Indicators | Status | Badge Color | Description | |--------|------------|-------------| | `draft` | grey | Not yet sent to parent | | `sent` | blue | Sent, awaiting payment | | `partially_paid` | amber | Some payments made, balance remaining | | `paid` | green | Fully paid | | `overdue` | red | Past due date, no full payment | | `cancelled` | grey (strikethrough) | Voided by admin | | `refunded` | purple | Payment refunded | ### Payment Status on Invoice Detail ``` ┌──────────────────────────────────────────────────┐ │ Invoice: INV-2026-0042 │ │ Status: Partially Paid │ │ │ │ Total Amount: ₵ 1,200.00 │ │ Amount Paid: ₵ 500.00 │ │ ───────────────────────── │ │ Balance Due: ₵ 700.00 │ │ │ │ ██████████░░░░░░░░░░░░░░░░░░ 42% paid │ │ │ │ Payment History: │ │ ├── Jun 15 — ₵ 500.00 — Card — ✓ Successful │ │ └── Remaining: ₵ 700.00 │ │ │ │ [Pay Balance] (primary) │ └──────────────────────────────────────────────────┘ ``` --- ## 3. PAYSTACK PAYMENT METHOD SPECIFICATIONS ### 3A. Card Payment (Inline Popup) ``` ┌──────────────────────────────────────────────────┐ │ │ │ ┌────────────────────────────────────────────┐ │ │ │ Paystack Secure Payment │ │ │ │ │ │ │ │ Amount: ₵ 1,200.00 │ │ │ │ │ │ │ │ Card Number │ │ │ │ ┌──────────────────────────────────────┐ │ │ │ │ │ 5061 0200 1234 5678 │ │ │ │ │ └──────────────────────────────────────┘ │ │ │ │ │ │ │ │ Expiry Date CVV │ │ │ │ ┌──────────────┐ ┌──────────────────┐ │ │ │ │ │ 12/28 │ │ ••• │ │ │ │ │ └──────────────┘ └──────────────────┘ │ │ │ │ │ │ │ │ Cardholder Name │ │ │ │ ┌──────────────────────────────────────┐ │ │ │ │ │ Kofi Asante │ │ │ │ │ └──────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────┐ │ │ │ │ │ Pay ₵ 1,200.00 │ │ │ │ │ └──────────────────────────────────────┘ │ │ │ │ │ │ │ │ 🔒 Powered by Paystack │ │ │ └────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────┘ ``` **Implementation:** - Paystack inline.js popup - No redirect — modal overlay on current page - Card validation happens client-side - On success: webhook fires to backend - Backend: creates payment record, updates invoice status - Frontend: polls for confirmation, then shows PAR-11 **States:** 1. Ready: Form displayed 2. Processing: "Processing..." spinner on button 3. Success: Auto-redirect to PAR-11 4. Failed: "Payment failed. Please try again." + retry button ### 3B. Mobile Money ``` ┌──────────────────────────────────────────────────┐ │ │ │ Select Provider │ │ ┌────────────────────────────────────────────┐ │ │ │ 📱 MTN Mobile Money ▾ │ │ │ └────────────────────────────────────────────┘ │ │ │ │ Mobile Number │ │ ┌────────────────────────────────────────────┐ │ │ │ +233 24 123 4567 │ │ │ └────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────┐ │ │ │ Send Payment Request │ │ │ └────────────────────────────────────────────┘ │ │ │ │ Providers: MTN / Vodafone Cash / AirtelTigo │ │ │ └──────────────────────────────────────────────────┘ ``` **Flow:** 1. Select provider (MTN/Vodafone/AirtelTigo) 2. Enter mobile number 3. Click "Send Payment Request" 4. Customer receives prompt on phone 5. Customer confirms on phone 6. System polls Paystack for status 7. On success: → PAR-11 **States:** 1. Ready: Provider + number input 2. Request sent: "⏳ Payment request sent to +233 24 123 4567. Please confirm on your phone." 3. Processing: "⏳ Waiting for confirmation..." 4. Success: → PAR-11 5. Failed/Timeout: "Payment was not confirmed. Please try again." ### 3C. Bank Transfer ``` ┌──────────────────────────────────────────────────┐ │ │ │ Virtual Account Details │ │ (Generated by Paystack) │ │ │ │ Bank: Guaranty Trust Bank │ │ Account Number: 9876543210 │ │ Account Name: RP Learning Portal │ │ Amount: ₵ 1,200.00 │ │ Reference: INV-2026-0042 │ │ │ │ ⚠ Transfer the exact amount and include the │ │ reference in your transfer description. │ │ │ │ ┌────────────────────────────────────────────┐ │ │ │ I have made the transfer │ │ │ └────────────────────────────────────────────┘ │ │ │ │ Status: ⏳ Waiting for confirmation... │ │ (Polling every 30 seconds) │ │ │ └──────────────────────────────────────────────────┘ ``` **Flow:** 1. Paystack generates virtual account 2. Display account details to parent 3. Parent makes transfer from their bank 4. Parent clicks "I have made the transfer" 5. System polls Paystack for confirmation 6. On success: → PAR-11 ### 3D. USSD ``` ┌──────────────────────────────────────────────────┐ │ │ │ Select Bank │ │ ┌────────────────────────────────────────────┐ │ │ │ 🏦 GTBank ▾ │ │ │ └────────────────────────────────────────────┘ │ │ │ │ Dial this USSD code on your phone: │ │ ┌────────────────────────────────────────────┐ │ │ │ │ │ │ │ *737*1200*42# │ │ │ │ │ │ │ │ [Copy Code] │ │ │ │ │ │ │ └────────────────────────────────────────────┘ │ │ │ │ Instructions: │ │ 1. Dial the code above on your phone │ │ 2. Enter your PIN when prompted │ │ 3. Confirm the payment │ │ 4. Click "I have completed the payment" below │ │ │ │ ┌────────────────────────────────────────────┐ │ │ │ I have completed the payment │ │ │ └────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────┘ ``` --- ## 4. RECEIPT SPECIFICATIONS ### Receipt PDF Layout ``` ┌──────────────────────────────────────────────────┐ │ │ │ [School Logo] RP LEARNING PORTAL │ │ Payment Receipt │ │ │ │ ───────────────────────────────────────────── │ │ │ │ Receipt #: REC-2026-0038 │ │ Date: June 15, 2026 │ │ Invoice #: INV-2026-0042 │ │ │ │ Student: Amara Asante │ │ Class: JSS 2 │ │ Parent: Kofi Asante │ │ │ │ ───────────────────────────────────────────── │ │ │ │ Payment Details: │ │ Method: Card (Paystack) │ │ Reference: PSK-xyz123 │ │ Amount: ₵ 500.00 │ │ Status: Successful │ │ │ │ ───────────────────────────────────────────── │ │ │ │ Invoice Summary: │ │ Total Amount: ₵ 1,200.00 │ │ Paid to Date: ₵ 500.00 │ │ Balance Due: ₵ 700.00 │ │ │ │ ───────────────────────────────────────────── │ │ │ │ This is a computer-generated receipt. │ │ For queries: finance@rplearning.com │ │ │ └──────────────────────────────────────────────────┘ ``` ### Receipt Number Format - Format: REC-YYYY-NNNN - Sequential per year - Auto-generated by ReceiptGeneratorService ### Receipt Delivery | Channel | Method | Timing | |---------|--------|--------| | Auto-email | SendGrid/TxtConnect | Immediate on payment success | | Download | DomPDF generation | On-demand | | Re-send | Email API | On-demand via PAR-11 button | --- ## 5. PAYMENT ERROR STATES ### Error Handling UI ``` ┌──────────────────────────────────────────────────┐ │ │ │ ❌ Payment Failed │ │ │ │ Reason: Insufficient funds │ │ │ │ Your card was charged but the payment could │ │ not be completed. No money has been deducted. │ │ │ │ Please try again or use a different payment │ │ method. │ │ │ │ ┌────────────────────────────────────────────┐ │ │ │ Try Again │ │ │ └────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────┐ │ │ │ Choose Different Method │ │ │ └────────────────────────────────────────────┘ │ │ │ │ Need help? [Contact Admin] │ │ │ └──────────────────────────────────────────────────┘ ``` ### Error Categories | Error | Display | Action | |-------|---------|--------| | Insufficient funds | "Insufficient funds" | Retry / change method | | Card declined | "Card was declined" | Retry / change method | | Network error | "Network error. Payment status unknown." | Check status / retry | | Timeout | "Payment timed out" | Check status / retry | | Duplicate | "This payment was already processed" | Show receipt | | Webhook failure | Silent — backend retry | Auto-retry 3x | --- ## 6. INVOICE PDF DOWNLOAD ### Invoice PDF Layout ``` ┌──────────────────────────────────────────────────┐ │ │ │ [School Logo] RP LEARNING PORTAL │ │ INVOICE │ │ │ │ Invoice #: INV-2026-0042 │ │ Date: June 10, 2026 │ │ Due Date: June 30, 2026 │ │ │ │ Bill To: │ │ Kofi Asante (Primary Guardian) │ │ kofi@example.com │ │ │ │ Student: Amara Asante │ │ Class: JSS 2 │ │ │ │ ───────────────────────────────────────────── │ │ │ │ Description Qty Unit Price Total │ │ ───────────────────────────────────────────── │ │ Tuition — Term 3 1 ₵ 800.00 ₵ 800.00│ │ Exam Fee 1 ₵ 200.00 ₵ 200.00│ │ Library Fee 1 ₵ 100.00 ₵ 100.00│ │ Activity Fee 1 ₵ 100.00 ₵ 100.00│ │ ───────────────────────────────────────────── │ │ Subtotal: │ │ ₵ 1,200.00 │ │ Discount: ₵ 0.00 │ │ ════════════════════════════════════════════ │ │ TOTAL: ₵ 1,200.00 │ │ │ │ ───────────────────────────────────────────── │ │ │ │ Status: Outstanding │ │ Payment due by June 30, 2026 │ │ │ │ Pay online at: https://portal.rplearning.com │ │ │ └──────────────────────────────────────────────────┘