Entities & Transactions
BayWise Payments organises financial data around two core concepts: entities (the financial subject) and transactions (the money movements attached to it). Understanding how they relate is essential to everything else in the system.
What is an entity?
An entity is the financial subject — the thing that money is being collected for or spent on. It groups all related transactions together into a single financial story.
Think of it this way: when a customer brings their car in for a brake replacement, that repair is the entity. The estimate, the invoice, the customer payment, the insurance claim, the parts expense — all of those are transactions hanging off that one entity.
Entity types
| Type | What it represents | Example |
|---|---|---|
| vehicle_repair | A single vehicle visit and the work performed | Brake pad replacement on plate ABC-1234 |
| parts_order | A purchase order for parts or materials | Bulk filter order from Bosch supplier |
| generic | Any other collection or payment not tied to a vehicle | Monthly rent payment, equipment purchase |
Lifecycle stages
Each entity type follows a defined lifecycle. Stages progress forward only — an entity cannot move backwards to a previous stage.
Vehicle repair:
estimate → approved → in_progress → delivered → invoiced → closed
This mirrors the workshop floor. A job starts as an estimate, gets customer approval, enters production, is delivered to the customer, invoiced, and finally closed once all money has settled.
Parts order:
ordered → confirmed → dispatched → delivered → invoiced → closed
Tracks the procurement lifecycle from purchase order through to supplier payment.
Generic:
open → closed
Simple two-stage lifecycle for anything that does not fit the other types.
Stage progression is forward-only. A vehicle repair that is “invoiced” cannot return to “in_progress”. This ensures the financial record accurately reflects real-world events.
What is a transaction?
A transaction is a single money movement — one inflow or one outflow — attached to an entity.
When Sharma Motors in Mumbai collects AED 3,200 in cash from a customer, that is one transaction. When they pay a parts vendor AED 1,100 by bank transfer for the same job, that is another transaction. Both hang off the same vehicle repair entity.
Transaction properties
| Property | What it stores |
|---|---|
| Amount | The monetary value including tax |
| Direction | inflow (collection — money coming in) or outflow (expense — money going out) |
| Method | How the money moves: cash, card, bank transfer, cheque |
| Category | Classification of the transaction (parts, labour, insurance, etc.) |
| Contact | The counterparty — customer, insurer, or vendor |
| Settlement type | instant (money received now) or credit (obligation created, settled later) |
| Settlement status | pending (money expected but not yet received) or settled (money in hand) |
| Credit terms | For credit settlements: Net-15, Net-30, Net-45, or Net-60 |
The two-moment model
Every financial event in BayWise Payments follows a two-moment model:
Moment A — Obligation created. The workshop and the counterparty agree that money will move. A credit sale is recorded, an insurance claim is filed, a vendor invoice is received. The transaction exists with settlement status pending.
Moment B — Money moves. Cash changes hands, a bank transfer clears, a card payment processes. The transaction moves to settlement status settled.
For instant payments (cash handed over the counter, card tapped at the terminal), both moments happen simultaneously. For credit arrangements, days or weeks may pass between Moment A and Moment B.
At Al Futtaim Auto in Dubai, insurance claims routinely have 30-45 days between Moment A (claim filed) and Moment B (insurer remits payment). The two-moment model tracks this gap explicitly rather than pretending money arrived when it has not.
Voiding — not deleting
BayWise Payments never deletes a financial record. When a transaction needs to be corrected, it is voided.
A voided transaction remains in the ledger as an immutable record — visible, auditable, but excluded from all balance calculations. Every void requires a reason, which is stored alongside the voided record.
Void-and-replace
When a financial field needs to change (wrong amount, wrong method, wrong contact), the system uses a void-and-replace pattern:
- The original transaction is voided with a reason
- A new corrected transaction is created
- The new transaction links back to the voided one via a parent chain
This creates a complete audit trail. At Muller Werkstatt in Berlin, an auditor can trace every correction back to the original entry and see exactly what changed and why.
Voided transactions are permanent. Once a transaction is voided, it cannot be un-voided. The correct workflow is always void-and-replace.
Idempotency and duplicate detection
Every transaction receives a unique idempotency key at creation time. If a network retry or double-tap attempts to create the same transaction twice, the duplicate is rejected silently — only one record is created.
Beyond the idempotency key, BayWise Payments runs duplicate detection: if a transaction with the same entity, contact, amount, and direction already exists within a 5-minute window, the system flags it for confirmation. The cashier can override the flag if the duplicate is intentional (two separate payments of the same amount from the same customer), but accidental duplicates are caught before they enter the ledger.
Expected amounts
Vehicle repair entities carry expected payment amounts that define how much money should be collected:
| Field | What it stores |
|---|---|
| Customer portion | What the customer owes — derived, never manually entered |
| Insurance portion | What the insurer owes (for insurance jobs) |
The customer amount is always computed: total expected minus insurance portion. This prevents data entry errors where the two halves do not add up to the whole.
For non-insurance jobs, the customer portion equals the full invoice (or estimate) amount.
Cached totals
Each entity maintains running totals (updated automatically) whenever a transaction is created, voided, or settled.
These running totals power the Collection Queue cards, the Financial Modal summaries, and the dashboard metrics. They are never manually set — the system guarantees they stay in sync with the underlying transactions.