Financial data looks simple at first: money comes in, money goes out, and the balance is the difference. In a real digital business, however, one sale can involve a supplier cost, a payment fee, customer credit, a wallet movement, and a later refund.
This article outlines a practical architecture for building a financial tracking API that stays reliable as a business grows.
1. Start with an append-only transaction model
Avoid treating the current balance as the primary source of truth. Store each financial event as a transaction and calculate balances from those records.
A useful transaction model can include:
- a unique transaction ID
- workspace or business ID
- transaction type: income, expense, transfer, refund, or adjustment
- amount and currency
- account or wallet
- category
- external reference
- timestamp and status
- metadata
For money, use an exact decimal type or integer minor units. Floating-point numbers can introduce rounding errors during reconciliation.
{
"id": "txn_01H...",
"type": "expense",
"amount": "149.00",
"currency": "THB",
"category": "supplier_cost",
"external_reference": "order_7842",
"status": "posted"
}
2. Separate business events from accounting entries
An order and a transaction are related, but they are not the same thing. A digital product order may generate sales revenue, supplier cost, a payment processing fee, customer credit usage, and a later refund.
Keep the order as the operational record and generate linked financial entries from it. This makes profit calculation clearer and prevents business logic from becoming tightly coupled to one balance column.
3. Make every write idempotent
APIs receive retries. Networks fail, workers restart, and webhook providers resend events. Without idempotency, one successful payment can be recorded twice.
Accept an idempotency key for every operation that creates a financial record:
Idempotency-Key: order-7842-payment-v1
Store the key together with the result. When the same key arrives again, return the original result instead of creating a duplicate transaction.
4. Use explicit states and an audit trail
Useful transaction states include pending, posted, failed, reversed, and archived. For financial records, a reversal is usually safer than physically removing data. An audit trail should show who changed the record, when it changed, and why.
5. Design for reconciliation
The number shown in your system will eventually need to match a bank account, payment gateway, supplier statement, or digital wallet.
Store the internal transaction ID, external transaction ID, order ID, provider, settlement date, and reconciliation status. A reconciliation process can then identify missing, duplicated, or mismatched records automatically.
6. Calculate profit from components
Revenue alone is not profit:
profit = revenue - supplier_cost - payment_fee - other_costs + adjustments
Keep every component queryable. This allows reports by product, category, channel, supplier, or date range and makes unexpected margin changes easier to investigate.
7. Secure the API by workspace and role
Every request should be scoped to a workspace. Roles might include owner, administrator, accountant, staff, and read-only viewer. API keys should have limited permissions and be revocable without affecting user accounts.
Also use rate limits, signed webhooks, encrypted secrets, audit logs, short-lived access tokens, and strict validation of currency and amount fields.
8. Automate through events
Publish events such as transaction.created, transaction.posted, order.paid, refund.completed, and credit.updated. Consumers can react asynchronously without slowing the original request. Use retries, dead-letter queues, and unique event IDs so failures can be recovered safely.
9. Build reporting on consistent definitions
Define income, expense, gross profit, net profit, outstanding customer credit, wallet balance, and unreconciled amount once. If the dashboard, export, and API each calculate a metric differently, users will stop trusting the system.
Final thoughts
A reliable financial tracking API is less about creating many endpoints and more about protecting the integrity of every financial event. Append-only records, idempotent writes, clear states, reconciliation references, and strong workspace isolation provide a foundation that can grow from personal expense tracking into business back-office automation.
This architecture is similar to the direction behind MeeTang, a financial management and back-office platform for individuals, online sellers, and digital businesses in Thailand.
If you are building an online store or digital product business, start by making every transaction traceable. Automation becomes much easier once the underlying financial data can be trusted.
Top comments (0)