Overview

This document outlines the processes, expectations, and technical requirements for managing opening balances and top-up transactions within Trac. These are critical components for initialising and maintaining accurate member balances when integrating external systems such as till systems or school business platforms.

Purpose

The primary objectives of this feature are:

• To initialise member balances when transitioning from a legacy system to Trac.

• To ensure continuous synchronisation of top-up transactions from integrated systems.

• To prevent account discrepancies, such as member accounts erroneously appearing in debt due to missing financial data.

Scope

This feature applies to:

• Any integration partner that maintains a record of member balances.

• Situations where existing balances must be transferred into Trac (e.g., onboarding a school previously using another system).

• Ongoing synchronisation of top-up transactions from third-party systems to Trac.

This does not cover sales, deductions, or non-top-up financial events.

Description

Opening Balances

Definition:

An opening balance is a transaction posted to a member’s Trac account that sets their starting balance. This occurs before any transactions (sales, deductions) take place.

Use Case:

For example, if a member has a £5 balance in a previous system (e.g., Arbor), and the new system (Trac) initialises them with a £0 balance, an opening balance transaction is needed to reflect the correct amount.

Transmission:

Balance data is typically available in Trac in two ways: either the integrator pushes it to Trac via the API, or Trac pulls it directly from systems like Arbor.

How to Send an Opening Balance:

Once members are matched between systems, the integrating system should post an ePayment transaction for each user with the balance value. E.g., a member with a -£320 balance in the legacy system should have an ePayment transaction of -£320 created in Trac.

Top-up Transactions

Definition:

A top-up is a transaction that increases the member's available balance and reflects real-world monetary deposits (e.g., online payments, cash at school, etc.).

Frequency Expectations:

Recommended: every 10 to 30 minutes for better accuracy and member experience.

Transmission:

• If using systems like Parent Pay, Trac will pull transactions.

• Other systems should push top-ups to Trac upon receipt or during regular sync intervals.

Required Fields:

• transactionDate: Date when the payment was actually made (not the sync/upload date).

  • Example: A parent tops up online on Monday, but the integration syncs on Tuesday — the transaction_date must be Monday.

• type: Reflects the method of payment used:

  • ePayment: Default for digital/online payments.

  • cash: For physical cash handled at school or via revaluation machines.

  • cheque: If payment was made by cheque.

  • directCredit: For card payments or direct bank transactions.

Top-up Reversals

If a top-up is incorrectly posted or cancelled, a contra transaction should be created.

This involves sending the same transaction data but with the negative amount, effectively cancelling the original. The contra transaction should have the type:cancellation. Note that a contra transaction is not the same as a refund. For example, if a cash top-up is received and then physically returned to the payer, this should be treated as a refund, not a cancellation, since the original top-up was not posted in error. You can find more information about how to handle refunds here.

Implementation

Posting Opening Balances

1. Match members between the external system and Trac.

2. For each member, create a transaction:

   • type: epayment

   • amount: Equal to the prior balance

   • transactionDate: Date the opening balances have been set

Posting Top-ups

1. At each top-up event, or at regular intervals:

   • Generate a transaction with:

     • Accurate transactionDate

     • Correct type field

     • Valid amount (positive or negative as needed)

2. Push to Trac via API or wait for Trac to pull, depending on integration.

Contra Transactions

If a transaction is invalidated:

• Post a transaction with all matching fields but the opposite amount.

• Ensure this is clearly flagged in the source system to prevent reprocessing.

Risks and Mitigations

• Incorrect opening balances leading to inaccurate member funds: Ensure all members are matched correctly and all balances are pushed/pulled before use
• Delayed top-ups causing member debt: Syncing top-ups at regular, short intervals. E.g. every 10 minutes
• Incorrect transaction type skews reporting: Ensure systems apply correct types per payment method
• Missed or failed transactions: Implement logging and reconciliation processes to detect and correct missing data