Financial Management Entities

1. Overview

Financial entities manage the complete financial lifecycle including orders, payments, general ledger accounting, and financial reconciliation. These entities support both event registration payments and membership fees.

Package: za.co.idealogic.event.domain
Repository: event-database
Total Entities: 7

2. Order Management

2.1. Order

Represents a customer order for event registrations, memberships, products, or services.

Key Relationships:

  • Many-to-one with Organisation

  • Many-to-one with User (customer)

  • One-to-many with OrderLineItem

  • Many-to-one with PaymentProcessor

  • One-to-many with GlTransaction

Attributes:

  • Order number (unique identifier)

  • Order date

  • Order status (pending, paid, cancelled, refunded, partially_refunded)

  • Total amount

  • Currency

  • Payment status

  • Payment method

  • Transaction reference

  • Customer information

Order Statuses:

  • Pending - Order created, awaiting payment

  • Paid - Payment received and confirmed

  • Cancelled - Order cancelled before payment

  • Refunded - Full refund processed

  • Partially Refunded - Partial refund processed

  • Failed - Payment failed

2.2. OrderLineItem

Individual items within an order (event entries, membership fees, products, add-ons).

Key Relationships:

  • Many-to-one with Order

  • References Product (optional)

  • References EventParticipant (for event entries)

  • References MembershipPeriod (for membership fees)

Attributes:

  • Line item description

  • Quantity

  • Unit price

  • Discount amount

  • Tax amount

  • Total amount

  • Item type (event_entry, membership, product, fee, discount)

  • Related entity reference

Line Item Types:

  • Event Entry - Registration for an event/race

  • Membership Fee - Membership payment

  • Product - Physical or digital product

  • Processing Fee - Transaction fees

  • Discount - Discount applied (negative amount)

  • Add-on - Optional extras (timing chip, t-shirt, etc.)

2.3. Product

Catalog of products and services that can be sold.

Attributes:

  • Product name

  • Description

  • SKU/product code

  • Price

  • Currency

  • Tax category

  • Active/inactive status

  • Stock tracking (optional)

Product Types:

  • Event merchandise (t-shirts, medals)

  • Timing chips

  • Race photos/videos

  • Training programs

  • Equipment rental

  • Insurance products

  • Donations

3. Payment Processing

3.1. PaymentProcessor

Configuration for payment gateway integrations.

Key Relationships:

  • Many-to-one with Organisation

  • One-to-many with Order

Attributes:

  • Processor name (PayFast, Stripe, PayPal, etc.)

  • Processor type

  • API credentials (encrypted)

  • Merchant ID

  • Configuration settings (JSON)

  • Active/inactive status

  • Supported currencies

  • Supported payment methods

Supported Processors:

  • PayFast (South African payment gateway)

  • Stripe (International)

  • PayPal

  • Manual payments (bank transfer, cash)

  • Organization-specific integrations

4. General Ledger

The general ledger entities provide double-entry accounting for financial tracking and reporting.

4.1. GlAccount

Chart of accounts defining the general ledger account structure.

Attributes:

  • Account number

  • Account name

  • Account type (asset, liability, equity, revenue, expense)

  • Parent account (for hierarchical structure)

  • Active/inactive status

  • Currency

Standard Account Types:

  • Revenue - Event fees, membership fees, product sales

  • Liability - Deferred revenue, refunds payable

  • Asset - Cash, accounts receivable, payment processor balance

  • Expense - Transaction fees, refunds issued

  • Equity - Organisation capital

Example Accounts:

4000 - Revenue
  4100 - Event Registration Revenue
  4200 - Membership Fee Revenue
  4300 - Product Sales Revenue
  4400 - Sponsorship Revenue

5000 - Expenses
  5100 - Payment Processing Fees
  5200 - Refunds
  5300 - Event Costs

1000 - Assets
  1100 - PayFast Balance
  1200 - Stripe Balance
  1300 - Bank Account

4.2. GlRecord

Individual general ledger entries (debits and credits).

Key Relationships:

  • Many-to-one with GlTransaction

  • Many-to-one with GlAccount

Attributes:

  • Debit amount

  • Credit amount

  • Record date

  • Description

  • Reference number

Accounting Rules:

  • Every transaction has at least two GlRecords

  • Total debits must equal total credits

  • Each record affects one GlAccount

4.3. GlTransaction

A complete financial transaction consisting of multiple GlRecords (double-entry).

Key Relationships:

  • One-to-many with GlRecord

  • Many-to-one with Order (optional - for order-related transactions)

  • Many-to-one with Organisation

Attributes:

  • Transaction date

  • Transaction type

  • Description

  • Status (draft, posted, voided)

  • Posted by (user)

  • Posted date

Transaction Types:

  • Payment Received - Customer payment

  • Refund Issued - Refund to customer

  • Fee Expense - Payment processor fees

  • Bank Transfer - Funds movement

  • Adjustment - Manual corrections

  • Closing - Period close entries

5. Reconciliation

5.1. Recon

Reconciliation records for matching payments, bank statements, and general ledger entries.

Attributes:

  • Reconciliation type (bank, payment processor, order)

  • Reconciliation date

  • Period start/end dates

  • Status (in_progress, completed, discrepancies)

  • Reconciled amount

  • Discrepancy amount

  • Notes

Reconciliation Types:

  • Bank Reconciliation - Match bank statements to GL

  • Payment Processor Reconciliation - Match processor reports to orders

  • Order Reconciliation - Verify order totals match GL

  • Period Close - Month/year-end reconciliation

Use Cases:

  • Daily payment processor reconciliation

  • Monthly bank reconciliation

  • Dispute investigation

  • Financial audit support

  • Variance analysis

6. Entity Relationships

Organisation
    |
    +----> PaymentProcessor
    |
    +----> Order -------- 1:N --------> OrderLineItem
    |        |                              |
    |        |                              +---> Product
    |        |                              +---> EventParticipant
    |        |                              +---> MembershipPeriod
    |        |
    |        +--------> GlTransaction
    |                       |
    |                       | 1:N
    |                       |
    +----> GlAccount <----- GlRecord

7. Example Transactions

7.1. Example 1: Event Registration Payment

Order #12345
  Customer: John Doe
  Date: 2025-01-15
  Status: Paid
  Total: R500.00

  OrderLineItems:
    - Marathon Entry: R450.00
    - Timing Chip: R50.00

GlTransaction for Payment:
  Type: Payment Received
  Date: 2025-01-15

  GlRecords:
    Debit:  Account 1100 (PayFast Balance) - R485.00
    Debit:  Account 5100 (Processing Fees) - R15.00
    Credit: Account 4100 (Event Revenue)   - R500.00

7.2. Example 2: Membership Fee Payment

Order #12346
  Customer: Jane Smith
  Date: 2025-01-16
  Status: Paid
  Total: R300.00

  OrderLineItems:
    - Annual Membership: R300.00

GlTransaction for Payment:
  Type: Payment Received
  Date: 2025-01-16

  GlRecords:
    Debit:  Account 1100 (PayFast Balance)    - R291.00
    Debit:  Account 5100 (Processing Fees)    - R9.00
    Credit: Account 4200 (Membership Revenue) - R300.00

7.3. Example 3: Refund Processing

Order #12345 (Original)
  Status: Partially Refunded
  Original Total: R500.00
  Refund Amount: R500.00

GlTransaction for Refund:
  Type: Refund Issued
  Date: 2025-01-20

  GlRecords:
    Debit:  Account 5200 (Refunds)          - R500.00
    Credit: Account 1100 (PayFast Balance)  - R500.00

8. Common Workflows

8.1. Order Creation & Payment Workflow

  1. User adds items to cart (create Order with status=pending)

  2. Add OrderLineItems for each item

  3. Calculate totals (items + fees - discounts)

  4. User selects PaymentProcessor

  5. Redirect to payment gateway

  6. Payment processor callback updates Order status

  7. Create GlTransaction and GlRecords

  8. Update EventParticipant or MembershipPeriod status

  9. Send confirmation email with receipt

8.2. Refund Processing Workflow

  1. Refund request initiated

  2. Validate refund eligibility

  3. Calculate refund amount (full or partial)

  4. Update Order status (refunded or partially_refunded)

  5. Process refund through PaymentProcessor

  6. Create GlTransaction for refund

  7. Update related entities (EventParticipant, MembershipPeriod)

  8. Send refund confirmation

8.3. Daily Reconciliation Workflow

  1. Export transaction report from PaymentProcessor

  2. Create Recon record

  3. Match processor transactions to Orders

  4. Match Orders to GlTransactions

  5. Identify discrepancies

  6. Investigate and resolve discrepancies

  7. Create adjustment GlTransactions if needed

  8. Mark Recon as completed

  9. Generate reconciliation report

8.4. Month-End Close Workflow

  1. Verify all orders have GlTransactions

  2. Run bank reconciliation

  3. Run payment processor reconciliation

  4. Review GlAccount balances

  5. Create period-end adjustments

  6. Post closing entries

  7. Generate financial reports

  8. Lock period (prevent backdated changes)

9. Multi-Tenancy Considerations

  • Each Organisation has its own:

    • Chart of accounts (GlAccounts)

    • Payment processor configurations

    • Order numbering sequence

    • Financial reporting

  • System administrators can:

    • Define standard chart of accounts templates

    • Configure global Products

    • Monitor cross-organisation transactions

  • Financial data is strictly organisation-scoped:

    • No cross-organisation financial queries

    • Each org maintains separate books

    • Independent reconciliation processes

10. Integration Points

10.1. Payment Gateway Integration

  • Order → PaymentProcessor → External Gateway

  • Webhook/callback handling for payment status

  • Refund API integration

  • Transaction status synchronization

10.2. Event/Membership Integration

  • OrderLineItem links to EventParticipant

  • OrderLineItem links to MembershipPeriod

  • Payment confirmation triggers activation

  • Refund triggers deactivation/cancellation

10.3. General Ledger Integration

  • Order payment creates GlTransaction

  • Automatic posting to GlAccounts

  • Financial reporting from GlRecords

  • Audit trail preservation

11. Entity Summary

Entity Primary Purpose Key Features

Order

Customer order/purchase

Status tracking, totals

OrderLineItem

Order details

Links to entities, pricing

Product

Product catalog

Pricing, SKU, inventory

PaymentProcessor

Gateway configuration

Multiple processors, encrypted credentials

GlAccount

Chart of accounts

Hierarchical structure, account types

GlRecord

Ledger entries

Debits/credits, double-entry

GlTransaction

Transaction container

Multiple records, balanced entries

Recon

Reconciliation tracking

Period-based, variance tracking

12. Reporting Capabilities

The financial entities support various reports:

  • Revenue Reports - By event, membership, product, period

  • Payment Processor Reports - By processor, reconciliation status

  • General Ledger Reports - Trial balance, income statement, balance sheet

  • Reconciliation Reports - Daily, monthly, variance analysis

  • Audit Reports - Transaction history, user actions

  • Tax Reports - VAT/sales tax reporting

13. Related Documentation