Financial Management Functional Requirements

1. Business Context

The Event and Membership Administration System requires financial management capabilities to track payment transactions, reconcile with payment processors, and maintain general ledger records for export to external accounting systems.

1.1. Business Drivers

  • Payment Verification - Confirm orders are correctly marked as paid or unpaid by comparing with payment processor records

  • Fee Tracking - Capture payment processor fees for cost analysis and accurate financial reporting

  • Audit Trail - Maintain complete record of all payment processor transactions

  • GL Integration - Record financial effect of orders for accounting purposes

  • Journal Export - Consolidate transactions for export to external accounting software

  • Delta Tracking - Handle order modifications after transactions have been journaled

1.2. Scope

This requirements document covers:

  • PayFast transaction reconciliation import

  • PayGate transaction reconciliation import

  • General ledger transaction creation from orders

  • Delta handling for post-journal order modifications

  • Journal creation and management

Out of scope:

  • Real-time webhook-based reconciliation

  • Automatic payment status correction (flagging only)

  • UI for reconciliation review

  • External accounting system integration (export only)

2. Payment Reconciliation Requirements

2.1. FR-FM-001: PayFast CSV Import

ID FR-FM-001

Title

PayFast Transaction CSV Import

Priority

High

Description

The system shall import PayFast transaction CSV exports to capture payment records and match them to orders.

Acceptance Criteria

  • CSV files up to 10MB supported

  • All PayFast transaction fields captured (25+ columns)

  • Duplicate transactions identified by PayFast Payment ID

  • Duplicate imports silently skipped (no error)

  • Import statistics returned (created, skipped, errors)

  • Customer name extracted from party field

Related

PayFast CSV Format Specification

2.2. FR-FM-002: PayGate CSV Import

ID FR-FM-002

Title

PayGate Transaction CSV Import

Priority

High

Description

The system shall import PayGate transaction CSV exports to capture payment records and match them to orders.

Acceptance Criteria

  • CSV files up to 10MB supported

  • All PayGate transaction fields captured (18 columns)

  • Duplicate transactions identified by Transaction ID

  • Duplicate imports silently skipped (no error)

  • Import statistics returned (created, skipped, errors)

  • Transaction fees calculated for successful payments

Related

PayGate CSV Format Specification

2.3. FR-FM-003: Order Matching

ID FR-FM-003

Title

Reconciliation Order Matching

Priority

High

Description

The system shall match reconciliation records to orders using merchant reference fields.

Acceptance Criteria

  • PayFast: Match using Merchant Payment ID field

  • PayGate: Match using Reference field

  • Handle reference formats: "12345" and "12345-12345"

  • Unmatched transactions stored without order link

  • Order link is informational only (no automatic status changes)

Notes

Order ID foreign key constraint intentionally omitted due to legacy data with PostIDs that don’t match current Order IDs. Matching performed at application level.

2.4. FR-FM-004: Fee Calculation

ID FR-FM-004

Title

Payment Processor Fee Calculation

Priority

Medium

Description

The system shall calculate or capture payment processor fees for each transaction.

Acceptance Criteria

  • PayFast: Fees imported directly from CSV (provided by PayFast)

  • PayGate: Fees calculated using formula: R2.00 + (gross x 3.5%) + 15% VAT

  • PayGate fees only calculated for successful transactions (result code 990018)

  • Net amount calculated: gross - fee - feeTax

  • All amounts stored with 2 decimal precision

Fee Formula (PayGate)

 
fee = R2.00 + (gross x 3.5%)
feeTax = fee x 15%
nett = gross - fee - feeTax

2.5. FR-FM-005: Discrepancy Detection

ID FR-FM-005

Title

Payment Discrepancy Detection

Priority

Medium

Description

The system shall enable detection of discrepancies between orders and payment processor records.

Acceptance Criteria

  • Reconciliation records queryable by organisation and date range

  • Matched and unmatched transactions distinguishable

  • Amount comparison between order and transaction possible

  • Report generation for discrepancy review

Notes

Automatic status correction is out of scope; system provides data for manual review.

3. General Ledger Requirements

3.1. FR-FM-010: GL Transaction Creation

ID FR-FM-010

Title

GL Transaction Creation from Order

Priority

High

Description

The system shall create a GL transaction with corresponding records when an order is paid.

Acceptance Criteria

  • One GlTransaction created per paid order

  • GlRecords created for each order line item (income)

  • GlRecord created for payment received (bank/asset)

  • GlRecord created for processing fees (expense)

  • Double-entry balance: total debits equal total credits

  • Transaction linked to source order

Record Structure
Account Type Description Sign

INCOME

Line item gross amount

Credit (negative)

BANK/ASSET

Payment received (total - fees)

Debit (positive)

EXPENSE

Processing fee

Debit (positive)

3.2. FR-FM-011: GL Account Mapping via PaymentProcessor

ID FR-FM-011

Title

GL Account Mapping via PaymentProcessor

Priority

High

Description

The system shall derive GL accounts from the PaymentProcessor associated with the Order. All financial postings for an order use accounts configured on the PaymentProcessor.

Acceptance Criteria

  • PaymentProcessor is required on Order before payment processing

  • PaymentProcessor has three GL account references:

    • bankAccount (required) - Asset account for net payment received

    • feeAccount (optional) - Expense account for processing fees

    • incomeAccount (required) - Income account for gross revenue

  • GlRecords use accounts from Order.paymentProcessor:

    • Bank/Asset debit → processor.bankAccount (consolidated per order)

    • Fee expense debit → processor.feeAccount (per line item)

    • Income credit → processor.incomeAccount (per line item)

  • Different PaymentProcessors may share or have distinct accounts

  • Orders without PaymentProcessor cannot generate GL transactions

Record Structure
Account Source Description Per Sign

processor.bankAccount

Net payment (gross - fees)

Order

Debit

processor.feeAccount

Line item fee

Line item

Debit

processor.incomeAccount

Line item gross

Line item

Credit

3.3. FR-FM-012: Order-GL Traceability

ID FR-FM-012

Title

Order to GL Traceability

Priority

High

Description

The system shall maintain bidirectional traceability between orders and GL records.

Acceptance Criteria

  • Each GlTransaction links to source Order

  • Each GlRecord optionally links to source OrderLineItem

  • Navigation from Order to GlTransaction supported

  • Navigation from GlRecord to OrderLineItem supported

  • GL records maintain audit trail independent of order changes

3.4. FR-FM-013: Delta Tracking

ID FR-FM-013

Title

Post-Journal Delta Tracking

Priority

High

Description

The system shall track order modifications as delta records when changes occur after journaling.

Acceptance Criteria

  • Pre-journal modifications: update existing GlRecords directly

  • Post-journal modifications: create new delta GlRecords

  • Delta records marked with isDelta flag

  • Delta records link to affected OrderLineItem

  • Next journal consolidation includes delta records

Decision Points
delta-decision-inline

3.5. FR-FM-014: Journal Creation

ID FR-FM-014

Title

Journal Creation for Export

Priority

High

Description

The system shall support creating journals that consolidate GL transactions for export to accounting software. Flexible filter parameters enable targeted journal creation by date range, registration system, and payment processor.

Acceptance Criteria

  • Journal created for specified criteria:

    • organisationId (required) - Organisation owning the orders

    • toDate (required) - Include transactions up to and including this date

    • fromDate (optional) - Include transactions from this date

    • registrationSystemId (optional) - Filter by registration system

    • paymentProcessorId (optional) - Filter by payment processor

    • description (optional) - Journal description

  • All ORDER-type transactions matching filters consolidated

  • Amounts aggregated by GL account

  • Consolidated GlRecords created in journal transaction

  • Source transactions marked as JOURNAL type (locked)

  • Journal transaction type is JOURNAL

  • Filter criteria stored with journal for audit/reporting

Consolidation

Multiple order transactions → single journal with aggregated account totals

Use Cases

  • Monthly journal for all orders: organisation + toDate

  • PayFast-only journal: organisation + toDate + paymentProcessorId

  • Event-specific journal: organisation + toDate + registrationSystemId

  • Period journal: organisation + fromDate + toDate

3.6. FR-FM-015: Journal Deletion

ID FR-FM-015

Title

Journal Deletion (Unwind)

Priority

Medium

Description

The system shall support deleting a journal, reverting included transactions to their pre-journal state.

Acceptance Criteria

  • Journal transaction deleted

  • Included transactions reverted to ORDER type

  • Source transactions again eligible for journaling

  • Delta records remain associated with source transactions

  • Audit trail maintained

Constraints

Only journals that have not been exported to external system should be deleted.

3.7. FR-FM-016: Steady State Balance

ID FR-FM-016

Title

GL Steady State Balance

Priority

Medium

Description

The system shall maintain GL balance where all accounts net to zero when fully exported.

Acceptance Criteria

  • Each transaction balances (debits = credits)

  • Journal transactions balance

  • After all income and assets transferred to external system, internal GL shows net zero

  • Balance validation available for reporting

4. Non-Functional Requirements

4.1. NFR-FM-001: Import Performance

ID NFR-FM-001

Title

Reconciliation Import Performance

Description

Reconciliation imports shall complete in reasonable time for typical file sizes.

Requirement

  • Files up to 1,000 rows: < 30 seconds

  • Files up to 10,000 rows: < 5 minutes

  • Progress feedback for long-running imports

4.2. NFR-FM-002: Data Integrity

ID NFR-FM-002

Title

Financial Data Integrity

Description

Financial records must maintain integrity and consistency.

Requirement

  • All monetary amounts use BigDecimal with 2 decimal precision

  • HALF_EVEN rounding for calculations

  • Double-entry validation on all GL transactions

  • Unique constraints on payment processor transaction IDs

  • Foreign key integrity for GL relationships

4.3. NFR-FM-003: Auditability

ID NFR-FM-003

Title

Financial Audit Trail

Description

All financial operations must be auditable.

Requirement

  • GL records immutable once journaled

  • Delta records track all post-journal changes

  • Timestamps on all transactions and records

  • Journal creation/deletion logged

  • Reconciliation import history maintained

4.4. NFR-FM-004: Security

ID NFR-FM-004

Title

Financial Data Security

Description

Financial data must be protected appropriately.

Requirement

  • Reconciliation import requires authenticated user

  • GL operations require appropriate role

  • Organisation-scoped access control

  • API endpoints secured with JWT authentication

5. Technology Decisions

The following technology decisions have been made (see design journal for rationale):

Component Decision Rationale

Entity Inheritance

JPA JOINED strategy

Clean separation of PayFast and PayGate specific fields

Discriminator

2-character codes

Consistent with existing enum patterns (Gender)

Money Type

BigDecimal

Sufficient precision, no external library dependency

CSV Parsing

SuperCSV

Already used in existing import services

Import Flow

Direct import

Fixed schema from payment processors, no mapping UI needed

GL Relationship

GlTransaction owns Order

FK on gl_transaction.order_id; Order has mappedBy inverse

GL Account Source

PaymentProcessor entity

Accounts (bank, fee, income) derived from Order.paymentProcessor

Journal Filtering

Optional multi-criteria

Flexible consolidation by date, registrationSystem, paymentProcessor

6. Related Documentation

7. Traceability

Artefact Reference

Design Thread

design-journal/financial-management/index.adoc

ADO Epic

Epic 35: Event Membership\Admin Service

Features

PayFast and PayGate Reconciliation, General Ledger Enhancement

Related User Stories

US-R1 to US-R9 (Recon), US-GL1 to US-GL9 (GL)