The TeamInvest Processor is a web application that retrieves payment transactions from FatZebra and Xero, and submits them to the TeamInvest Spring Boot API for processing into the TIMMS system.

All operations are manual — a user selects a date range, fetches transactions, reviews them, and submits with a passcode. The system records every run for audit purposes.

Key concepts

• Fetch — retrieves live transactions from the gateway (FatZebra or Xero) for a selected date range. Nothing is saved at this point.
• Process — submits the fetched (or selected) transactions to the TeamInvest API and records the result in the database.
• Processed / Pending — after fetching, rows already in the database are highlighted as ✓ Done. New rows show as Pending.
• Idempotency — the system prevents duplicate submissions. If a transaction has already been processed, the TeamInvest API will skip it and report it in skippedTxnIds.

The Dashboard provides an at-a-glance view of the system status. It shows the last run time and result for both FatZebra and Xero, along with database health.

• Last run — date and time of the most recent processing run for each service.
• Transactions — number of transactions submitted in the last run.
• Status badge — green Success or grey Unknown if no run has occurred yet.
• System health — confirms the SQL Server connection is active and shows last run timestamps for both services.
• View & process — links directly to the FatZebra or Xero transaction page.

The FatZebra page retrieves credit card payment and refund transactions from the FatZebra gateway for a selected date range, lets you review and select them, then submits them to the TeamInvest API.

Step 1 — Select date range and fetch

Set the From date and To date fields then click ↓ Fetch from FatZebra. Both dates default to today. The last dispatch banner at the top shows when the page was last successfully processed.

Step 2 — Review the live results grid

After fetching, all transactions for the selected period are displayed. The summary badge shows how many purchases, refunds, and already-processed rows were found. Rows already submitted to TeamInvest are automatically highlighted as ✓ Done — these can safely be skipped.

Already-processed rows

When fetching a date range that overlaps with a previous run, already-processed rows are highlighted in grey with a ✓ Done badge. A warning note appears beneath the toolbar indicating how many rows are already processed.

Step 3 — Select records (optional)

By default all fetched rows will be processed when you click Run. Use the checkboxes to select specific rows only — the Run button label updates to show the count. The header checkbox selects or deselects all rows at once.

Step 4 — Enter passcode and run

Enter your personal passcode and wait for the green owner name confirmation, then click ▶ Process. The result badge appears immediately on completion.

The Xero page retrieves fully paid accounts receivable invoices from Xero filtered by FullyPaidOnDate. Only ACCREC invoices with status PAID are returned. Contact Account Numbers are automatically cross-referenced from Xero contacts to populate the CiRef (member reference) field.

Step 1 — Select date range and fetch

Set From date and To date — both filter by FullyPaidOnDate — then click ↓ Fetch from Xero. The total amount and invoice count are shown in the grid footer.

Step 2 — MPAY checkbox (payment type)

Each invoice has an MPAY checkbox in the last column before Processed. This controls the txnType sent to the TeamInvest API:

• Unticked (default) — txnType = 21 — Auto DDR payment.
• Ticked — txnType = 20 — Manual MPAY payment.

Tick the MPAY checkbox on any invoice that was paid manually rather than via direct debit.

Step 3 — Select records (optional)

Use the row checkboxes on the left to select specific invoices for processing. Leave all unchecked to process all fetched results.

Step 4 — Enter passcode and run

Enter your passcode, wait for the green owner confirmation, then click ▶ Process.

Each user is assigned a named passcode in the application configuration. Passcodes authorise a processing run and identify who performed it in the logs.

How to use

1. Type your passcode into the Passcode field.
2. When you move out of the field, validation runs automatically.
3. If valid, your name appears in green next to the field and the Run button becomes active.
4. If invalid, the field turns red — check your passcode and try again.
5. After a successful run the passcode field is automatically cleared.

A complete processing run follows this sequence:

1. Select the date range.
2. Click Fetch — review the results, note any already-processed rows.
3. Optionally tick specific rows to process a subset only.
4. For Xero — optionally tick MPAY on any manual payment invoices.
5. Enter your passcode and wait for the green name confirmation.
6. Click ▶ Process.
7. Each transaction is submitted individually to the TeamInvest API.
8. Results are saved — the page auto re-fetches and processed rows update to ✓ Done.
9. The passcode field is cleared automatically.

Result badge meanings

• Done by Alice — 5 processed, 0 skipped — all transactions submitted successfully.
• Done by Alice — 3 processed, 2 skipped — some transactions were already in the TeamInvest system (duplicates skipped).
• Completed with 1 error(s) — one or more transactions failed. The rest were still processed.

The Dispatch Logs page shows a full history of every processing run. Each entry records the service, time, transaction count, success status, and any errors.

• Service — FatZebra or Xero, shown as a coloured badge.
• Sent at — timestamp of when the run was performed.
• Transactions — number of transactions submitted in that run.
• Status — Success or Failed.
• Error — if any transactions failed, the error detail is shown here.

The Idempotency page shows every individual transaction that has been processed, with its transaction ID, status, processing timestamp, and which dispatch run it belonged to. Rows can be filtered by service using the FatZebra / Xero buttons.

Idempotency ensures the same transaction is never submitted twice. Protection exists at two levels:

• Local database — the processor checks this table before submitting and highlights already-processed rows as ✓ Done in the live grid.
• TeamInvest API — the Spring Boot API has its own duplicate protection and reports duplicates in skippedTxnIds.

Passcode field turns red immediately

The passcode does not match any entry in the system. Check with your administrator that your passcode is correct and active in appsettings.json under Processing.Passcodes.

Fetch returns no transactions

Check the date range. FatZebra uses the transaction date; Xero uses FullyPaidOnDate. Ensure the dates match when payments were actually settled or paid in each system.

Rows still showing as Pending after processing

The page automatically re-fetches after a successful run and updates processed rows to ✓ Done. If rows still show as Pending, click Fetch again manually to refresh.

Process button is disabled

The Run button requires two conditions: fetched results must be present in the grid and a valid passcode must show the green owner name. Fetch first, then enter your passcode.

TeamInvest API error during processing

The error detail appears in the result badge. Common causes:

• txnRef not found — the CiRef (Account Number) does not match a member in TIMMS. Check the contact's Account Number in Xero.
• paymentReference too long — transaction reference exceeds 50 characters.
• API unreachable — check network connectivity to online.consciousinvestor.com.

Database shows as unhealthy on Dashboard

The SQL Server connection is unavailable. Check that SQL Server is running and the connection string in appsettings.json is correct.

Xero invoices missing Account Number (CiRef blank)

The contact in Xero does not have an Account Number set. Account Numbers must be populated on Xero contacts for the CiRef to be resolved correctly. Update the contact in Xero and re-fetch.