Core Finance objects and relationships

A Finance object is a record with its own identity, lifecycle, permissions and evidence. Related objects can share an amount without becoming the same record.

Audience: bursars, accountants, cashiers, auditors, implementers and support analysts
Learning time: 35 minutes

Learning outcomes

You will be able to:

• identify the record that owns each important fact;
• explain how totals and balances are related;
• recognise source, actor and status evidence;
• distinguish editable configuration from controlled transaction history;
• trace a student obligation from invoice to accounting and reconciliation.

Object classes

Class	Objects	Main question
Master/configuration	school fee, payment plan, GL account, bank setting, receipt template, approval matrix	How should future Finance work behave?
Obligation	invoice, invoice line, credit note	What is owed or reduced?
Collection	payment, allocation, receipt	What was received and where was it applied?
Accounting	journal entry, GL account, statement row	How was the event classified and reported?
External/settlement	payment attempt, bank statement line, provider callback	What happened outside or at the integration boundary?
Control/evidence	approval history, audit event, reconciliation record, certification	Who reviewed the action and what proves completion?

Identity rules

Every important object has a technical identifier. Several also have a human-readable number.

Object	Technical identity	Human-readable identity
School fee	UUID	optional fee code or schedule reference
Invoice	UUID	invoice number
Credit note	UUID	credit note number
Payment	UUID	sequential payment number
Receipt	UUID	school-scoped receipt number
Journal entry	UUID	entry number where surfaced
GL account	UUID	account code
Bank statement line	UUID	bank/provider references and statement context

Use the human-readable number when speaking to users and the UUID/request ID when support needs exact evidence.

School fee

Definition

A school fee is a pricing configuration record owned by a school. It can define:

• academic year and optional term;
• fee name, code, type and category;
• audience and grade/class/student-type scope;
• positive amount and currency;
• payment frequency, due date and grace rules;
• late-fee, discount, scholarship, installment and refund metadata;
• accounting and cost-centre codes;
• approval, effective-date and audit metadata.

Boundaries

A school fee:

• does not by itself create a student debt;
• can be active or inactive;
• can be soft-archived;
• can be approval-controlled;
• can carry localisation fields without proving statutory compliance.

Invoice

Definition

An invoice is the student obligation record.

Amount model

The verified rules are:

• at least one line item is required;
• subtotal must equal the sum of line-item totals;
• total must equal subtotal plus tax minus discount within tolerance;
• amount outstanding defaults to total minus amount paid;
• payment status derives as pending, partial or paid.

Two status dimensions

Dimension	Examples	Meaning
Approval status	draft, pending, approved, rejected, cancelled	governance state
Payment status	pending, partial, paid	settlement summary

An invoice can be approved but unpaid. Do not combine the dimensions.

Snapshot evidence

An invoice can retain a fee schedule snapshot. That preserves pricing context even if the fee configuration later changes.

Credit note

A credit note is a positive-value adjustment record that can be applied against an invoice.

Key fields include:

• source invoice and student;
• credit note number and date;
• reason code and description;
• amount, applied amount and remaining amount;
• status and approval status;
• approver and history.

Verified rules include:

• amount must be positive;
• remaining amount cannot be negative;
• only draft credit notes can be updated;
• only approved credit notes can be applied.

Payment

Definition

A payment is the recorded incoming-funds object.

Important facts include:

• student and anchor invoice;
• payment number and date;
• positive amount and currency;
• payment method and channel;
• payer and method-specific references;
• payment status;
• verification, reconciliation and refund flags;
• allocations and receipt links;
• actor and timestamps.

Independent state dimensions

A completed payment can still be unverified, unallocated and unreconciled.

Method-specific evidence

Method family	Important additional evidence
Bank transfer	bank name, bank reference, account context
Mobile money	provider/number and mobile-money reference
Cheque	cheque number and optional cheque date
Card/POS	last four digits; optional brand, terminal, authorisation and batch metadata
Provider channel	gateway reference, attempt and callback evidence

Payment allocation

An allocation contains at least:

• invoice ID;
• amount;
• currency;
• optional allocation notes.

The sum of manual allocations cannot exceed the payment amount. An allocation changes how the payment is applied; it does not create additional money.

Receipt

Definition

A receipt is a numbered proof document issued for a payment.

Key relationships:

Important receipt facts include:

• source payment and student;
• receipt number, date, type, amount and currency;
• received-from and payment-description text;
• line items and invoice allocations;
• issuer, delivery and location evidence;
• cancellation, duplicate and approval evidence;
• template/version metadata.

Cancellation boundary

Receipt cancellation:

• sets the receipt cancellation evidence;
• updates approval status to cancelled;
• clears the linked payment’s receipt ID.

It does not by itself create a payment refund.

GL account

A GL account is a Chart of Accounts record.

Field	Meaning
Account code	stable classification code
Account name	human-readable description
Account type	asset, liability, equity, revenue or expense
Normal balance	derived debit or credit behaviour
Header flag	grouping-only versus posting account
Active flag	whether it is available for use
School ID	school override/specific account when present
Parent ID	hierarchy relationship
Currency	optional account currency context

School-scoped lookup uses an exact school account first and a tenant-default account second.

Journal entry

The current GL API models a journal entry with:

• entry date;
• one debit account;
• one credit account;
• positive amount;
• description;
• source type and source ID;
• school and currency;
• optional cost-centre and revenue-stream codes;
• status draft, posted or reversed.

The debit and credit accounts must differ, exist, be active and not be headers.

Payment attempt

A payment attempt represents provider interaction state, retry and callback investigation. It belongs to Payments & Banking, not to the invoice balance itself.

Use attempt evidence when:

• the provider is pending;
• checkout was abandoned;
• a callback is delayed or duplicated;
• a user is considering trying again;
• provider and Makronexus states disagree.

Bank statement and line

A bank statement is an external container. A line represents one bank-side movement.

A line can include date, amount, currency, description and bank reference. Matching it to a payment is a reconciliation decision, not a billing decision.

Approval, audit and reconciliation evidence

Approval history

Records status changes, actor, time and comment where supported.

Audit event

Records the application mutation boundary. It supports traceability but does not replace business approval.

Reconciliation evidence

Links or compares internal and external records. Evidence can include a batch ID, bank statement line ID, reconciler and time.

Full trace example

Immutability and correction principles

Situation	Safe conceptual response
Pricing configuration wrong before use	correct or archive under its permission and approval rules
Draft object wrong	update if the object’s workflow allows
Approved object wrong	follow its reject, cancel, credit or controlled-change route
Posted journal wrong	create an offsetting reversal
Reconciled payment wrong	do not edit blindly; investigate and use authorised correction
Receipt document wrong	duplicate, resend or cancel as appropriate; correct the payment separately if money is wrong
Provider state uncertain	inspect the existing attempt/callback before retrying

Verification checklist for any object

• Correct tenant and school
• Correct object type
• Correct ID or human-readable number
• Correct amount and currency
• Correct status dimensions
• Correct actor and timestamp
• Correct source and related-object links
• Correct approval evidence
• Correct downstream balance or journal effect
• Correct external/reconciliation evidence where applicable

Practice

Tariro’s invoice is approved and shows partial. The linked payment is completed, fully allocated, not verified and not reconciled.

Explain each state without calling the record “finished.”

Answer: the obligation was approved; some but not all of it is settled; Makronexus recorded the payment; all payment value is assigned; internal verification and external reconciliation remain incomplete.