Getting Started

Q: What is the ideal sync rate between Trac and an integrator’s system?

A: Every 10 to 15 minutes between the systems.

Q: Why am I receiving an "Invalid Bearer Token" error when authenticating with Trac?

A: The "Invalid Bearer Token" error typically occurs when the JWT (JSON Web Token) is not generated or formatted correctly. Here are key points to check:

1. JWT Algorithm: Ensure that you're using the RS256 algorithm for generating the JWT, as Trac expects this.
2. JWT Structure: Your JWT should include the following claims:
   • iat (Issued At): The time the token was issued.
   • exp (Expiration Time): When the token expires.
   • aud (Audience): Should be set to "https://trac.mypebble.co.uk/" (or "https://trac-demo.stage.pebble.cloud" for demo environments).
   • iss (Issuer): Your installation app slug - This will be provided by Pebble

Example decoded JWT:

json
Copy code
{
  "iat": 1715872650,
  "exp": 1715901450,
  "aud": "https://trac.mypebble.co.uk/",
  "iss": "parentpay"
}

3. Example Code (Typescript): Here’s a sample function for generating a valid JWT using the RS256 algorithm in Typescript:

typescript
Copy code
import * as jwt from 'jsonwebtoken';

export const createJwt = (privateKey: Buffer, issuer: string): string => {
  const payload = {};

  const options: jwt.SignOptions = {
    algorithm: 'RS256',
    audience: 'https://trac.mypebble.co.uk/',
    issuer,
    expiresIn: '8h',
  };

  const myJwt = jwt.sign(payload, privateKey, options);
  return myJwt;
};

4. Token Validation: Verify that the iat, exp, aud, and iss claims are correct as per the JWT specification.

By following these guidelines, you should be able to resolve the "Invalid Bearer Token" error when authenticating with Trac.

Q: How can schools or integrators ensure opening balances are pulled into Trac if they don't want to push balances to Arbor?

A: If a school does not want to push balances into Arbor (which are then pulled by your system), there are alternative methods for managing opening balances:

1. Direct Transaction Creation in Trac: An integrator can create transactions directly in Trac for each person. This method functions similarly to pushing balances and avoids manual CSV uploads.
2. CSV Upload via Integrator System: While schools cannot upload a CSV directly into Trac, if the integrator offers a feature within their system (such as AMI or Relish) that allows the customer to upload a CSV of balances, the integrator can then send these balances to Trac as top-ups.

Note: Schools don't have direct access to Tali, so this process would need to be facilitated through the integrator's system.

Credits, Purses and Transactions

Q: How does Trac prioritise the assignment of credits to purses?

A: Currently, Trac does not prioritise credits based on any specific criteria such as session type or ranking. When multiple credit purses are linked to a person, Trac assigns credits based on the transaction date. The earliest available credit is used first. However, there are no predefined rules or prioritisation mechanisms (e.g., Free School Meals over Universal Infant Free Meals) in the system at this stage.

Future plans for Trac include introducing session-based credit assignment, where credits will only apply during certain times (e.g., lunch or after-school sessions), but this functionality has not yet been implemented.

Q: Can I use the externalIds field to store our transaction metadata?

A: Yes, using the externalIds field to store your transaction metadata is acceptable.

Q: What controls the process where money is deducted from the cash purse until the sales purse balance returns to zero?

A: This process is handled by a mechanism that runs every 5 minutes to process all sales in the sales purse. If it's not happening in your test app, please provide specific member and transaction details.

Q: Are transfers between the cash and sales purses represented as transactions?

A: No, this is a background process. You won't see transfers, but any sales covered by credits will have the credit.creditPortionOfSale field set for the amount covered by credits.

Q: Should we consider synced transactions as applied balances or wait for state-based flags to be processed?

A: Transactions against the cash or credit purses update the balance immediately, without further processing. For sales purse transactions, the balance updates when the sale is processed. You can track the status using the state field, which will be either "processed" or "notProcessed".

Q: How should integrators differentiate between new and already synced transactions?

A: Implement a "windowing" method by using the Get organization transactions endpoint with the member_txns=true query parameter to retrieve purse transactions. You can filter using the meta.createdAt.gt parameter, which gets all transactions created after a specific date/time. We recommend storing the date/time of the last transaction retrieved and then querying for transactions created 15 minutes before that timestamp to ensure no data is missed.

Q: What parameters should we use to filter transactions efficiently?

A: Use the meta.createdAt.gt parameter to filter transactions created after a specific point. Additionally, store the time of the last transaction retrieved and subtract 15 minutes from it to ensure complete coverage. Avoid relying solely on transactionDate, as backdated transactions may exist.

Q: How should we process onsite top-ups made with cash through our top-up machines to ensure balances stay in sync?

A: For onsite top-ups using notes and coins, you'll need to send the top-up data to us so we can update the corresponding balances. These top-ups should be posted following the process outlined in our Till System Integrators Guide. Since the payments are made in cash rather than through an online payment provider, the type field for these top-ups should be set to cash. This ensures both systems remain synchronised.

Members

Q: Why do all transactions need to be assigned to a member?

A: All transactions must be assigned to a member to maintain accurate financial tracking and balance management. Each member has a balance, and when a transaction occurs, it needs to either debit or credit that balance. If a transaction isn't linked to a member, there would be no account to adjust, which would break the system's core concept. This would lead to issues like sales not balancing with payments, which is critical for processes like double-entry bookkeeping.

Without assigning transactions to a member, it would be as though money were being "invented" without a source, leading to incorrect financial reporting. For situations where a transaction doesn't correspond to a specific individual, such as departmental expenses, fake or proxy members can be used to ensure accurate accounting.