Understanding Purse Management in Trac

When integrating with Trac, it's essential to understand how the system manages financial transactions using "purses."

Trac employs two types of purse by default for each member - cash purses and sales purses. There are also optional credit purses that can be created via the API.

Here’s a breakdown of how these purses work and interact within the system:

Default Purses: Cash and Sales

Upon creating a new member in Trac, two purses are automatically generated:

• Cash Purse: This is the default purse, identified by a static ID, default. All top-up transactions, such as those from online payment systems (i.e. ParentPay) are credited to this purse. The cash purse can have a positive, zero, or even negative balance. Any refunds should be created against this purse too.
• Sales Purse: This purse, identified by the ID sales, is where all sales transactions are recorded. Transactions created against this purse will automatically gain a “state” field, which by default will be “notProcessed”.

Internal Sales Processing

Trac has an internal sales processing mechanism designed to balance out the sales purse. Here's how it works:

1. The system checks for any unprocessed sales in the sales purse (I.e. any sales where the state field has the value notProcessed).
2. It then looks for any credit purses that have a positive balance.
3. Funds from these purses are automatically transferred to cover the sales in the sales purse until the sales purse balance returns to zero.
4. If there are not enough funds in any credit purses (or no credit purses exist), it will start deducting money from the cash purse.

Any sales that are covered by credits will have the creditPortionOfSale field set in the credit namespace.

This process ensures that while the sales purse reflects all sales, the actual balance management happens in the other purses, and in the appropriate priority order.

Credit Purses

Credit purses offer a flexible way to manage specific types of credits, such as free school meals or duty meals. These purses are:

• Unique Per Member: Unlike the default and sales purses, each credit purse has a unique ID and must be created via the API.
• Customisable: Credit purses can have specific names (e.g., "Free School Meals") and balances topped up as needed, in the title field.
• Can have validity periods: Each credit purse can have a validFrom and validTo date. If a credit purse is beyond or before its validity period, it is considered invalid, and funds will not be drawn from it during sales processing.
• Able to automatically create credits: By specifying the amount, creditApply, and expiryDuration in the credit namespace, credits can automatically be created at the set creditApply time and will expire after the number of days in expiryDuration has passed (I.e. any credits that are left over will be negated by a clearedCredit transaction). See below for more information.

Sales Processing with Credit Purses

When a sale is recorded, Trac’s processing prioritises the deduction of funds in the following order:

1. Valid Credit Purses: The system first looks for credit purses that are valid (i.e., within their specified date range) and with sufficient balance.
2. Default Cash Purse: If no valid credit purses are available or if the credit purses do not have enough funds to cover the sale, the system then deducts from the default cash purse.

It's important to note that this order of deduction is fixed, and developers do not have the option to set custom priorities.

Automatically Creating/Clearing Credits

Trac is able to automatically create transactions with the type credit based on fields set in the credit purse. This allows organisations to allocate and sweep down credits according to their needs.

This is set up by setting the fields in the credit namespace of a purse. These fields are:

• amount: This is the amount that the credit should be. E.g. if set to 2.50, credits worth 2.50 will be created.

• creditApply: This is a string in a crontab format that is used to specify when exactly the credit should apply. The crontab format allows for fine-tuning credits, such as making it apply at a specific time for a specific day in a specific month, etc.

  An example crontab is 30 9 * * 1-5. This would make the credit be applied at 9:30 am, Monday - Friday.

  You can validate your crontab using https://crontab.guru/

• expiryDuration: This is how many days the credit is active for. If set to 1, the credit will expire at midnight. This can be used for allowing roll-over.

  At the end of the “expiryDuration”, if any credits haven’t been taken (the purse still has a positive balance), Trac will automatically create a transaction to set the purse’s balance to 0. This transaction will have the type “clearedCredit”.

Reporting and Data Handling

When generating reports using Trac, such as those for free school meals:

• Individual sales that have been covered by any credits will have the creditPortionOfSale field in the credit namespace filled out. It does not specify what credit purse was used. Sales can be covered by multiple credits (e.g. a £5 sale can be fully covered by a £2.50 FSM and a £2.50 UIFSM credit)

• The sales transactions will remain in the sales purse after being processed. The sales themselves do not move purses, and funds are not physically moved between purses. Instead, the sales purse's balance is offset by transferring funds internally from the appropriate purses.

• Pre-orders should be sent as transactions with the transactionDate set to the future planned fulfilment date/time. These pre-orders will adjust the balance at the point the transaction is created. No additional transactions, or changes, should be sent as part of fulfilment - pre-orders are assumed to be fulfilled on the transactionDate. If the pre-order is cancelled then it should be cancelled/refunded as usual.

This approach allows for clear tracking and reporting of how credits are utilised over time, providing transparency and accountability in financial management within the Trac system.

Understanding how Trac manages these purses is crucial for effective API integration. By leveraging the default cash and sales purses, along with the flexibility of credit purses, developers can create robust financial tracking mechanisms that ensure all transactions are properly accounted for, reported, and balanced according to the system's internal rules