CH19-02: Financial Requirements, Boundaries, and Invariants
Goal
Define the requirements, ownership boundaries, and invariants that the payments, billing, and settlement engine must protect before choosing services or drawing a target architecture.
The Short Version
In a normal commerce feature, a team might start by asking which service can store data or process requests. In finance architecture, that is too late in the thinking process. Start by naming what must remain true even when a user retries, a provider times out, a message is delivered twice, a seller payout is delayed, or a settlement file does not match internal records.
Those truths are called invariants. An invariant is a rule the system must protect under normal operation and failure. For example: one approved refund request should not create two refunds, and every seller payout should be traceable to orders, fees, taxes, adjustments, and settlement records.
The durable idea is:
Financial architecture starts by naming the invariants that must remain true under failure.
If the invariants are vague, the implementation will hide financial risk inside application code, database updates, support scripts, and manual finance work.
Core Financial Invariants
The exact rules depend on the business, payment providers, countries, sellers, and products involved. A practical architecture conversation should still name the common invariants early.
| Flow | Invariant | Evidence to keep | Failure response |
|---|---|---|---|
| Authorization | A checkout attempt maps to one trackable authorization decision. | Payment intent, provider request, provider response or pending status. | Return known status or continue investigation instead of creating a new intent blindly. |
| Capture | A fulfilled order should not be captured twice. | Capture command, idempotency key, provider correlation, ledger event. | Detect duplicate requests and return the existing result. |
| Refund | One approved refund should not create multiple provider refunds. | Refund request, approval, provider correlation, refund ledger entry. | Resume or return the known refund status after timeout. |
| Invoice | Invoice records should explain what was billed and why. | Order lines, tax, discounts, fees, invoice number, adjustments. | Block or flag inconsistent invoice generation. |
| Seller payout | Seller payout should be traceable to eligible orders, fees, taxes, returns, and adjustments. | Payout batch, seller balance, commission, settlement reference. | Hold or adjust payout when reconciliation fails. |
| Settlement | Provider settlement should reconcile against internal financial records. | Settlement file, internal ledger, provider transaction IDs. | Create exceptions for investigation and correction. |
| Reporting | Reports should be explainable from controlled records. | Ledger, invoice, settlement, reconciliation, adjustment records. | Avoid manual report edits that bypass audit trails. |
Notice the pattern: the invariant is not "the API should return 200." The invariant is a business truth that must remain explainable.
Boundaries To Keep Clear
The finance engine should not become one large service that owns every money-related noun. It needs clear boundaries so teams can reason about ownership, security, failure, and change.
Checkout boundary
Owns customer interaction and order confirmation timing.
Payment provider boundary
Owns calls to external payment providers and provider correlation.
Fraud and risk boundary
Owns risk scoring, review, approvals, holds, and policy decisions.
Tax and invoice boundary
Owns tax calculation inputs, invoice generation, and invoice corrections.
Ledger boundary
Owns durable financial facts and controlled adjustments.
Payout and settlement boundary
Owns seller balances, payout batches, provider settlement, and reconciliation.
Support and reporting boundary
Owns investigation views, finance reports, and operational explanations.These boundaries can be implemented as separate services, modules, workflows, or data ownership areas. The important point is that the architecture does not blur who owns the financial truth.
Requirements That Shape The Design
Financial requirements are more than functional features. They include operational and control expectations.
| Requirement area | Architecture meaning |
|---|---|
| Idempotency | Repeated requests must not create duplicate money movement. |
| Correlation | Internal records must connect to provider transaction IDs and workflow IDs. |
| Auditability | Administrative and automated actions must be traceable. |
| Retention | Records may need to be retained according to business and compliance requirements. |
| Privacy | Sensitive payment, customer, seller, and tax data should be minimized, masked, tokenized, or protected as appropriate. |
| Authorization | Only approved identities and workflows should perform financial actions. |
| Regional constraints | Currency, provider, tax, data residency, and settlement rules may vary by market. |
| Support investigation | Support teams need safe views that explain status without exposing unnecessary sensitive data. |
| Finance operations | Finance needs reconciliation, exception handling, adjustments, and reporting controls. |
Do not worry if every term is not fully familiar yet. The practical question is: what must still be true when the happy path breaks?
Example: A Refund Retry
A customer returns an item. A support agent approves the refund and clicks submit. The refund service calls the payment provider, but the response times out. The support agent refreshes and tries again.
Without an invariant, the second attempt might create a second refund. With an invariant, the platform treats the refund request as a command with a stable idempotency key. The system checks whether this refund was already requested, whether a provider correlation exists, and whether the current status is succeeded, pending, failed, or unknown. It returns the known result or continues the same refund workflow. It does not blindly create another provider request.
The evidence path matters too. Support should see the refund status. Finance should see the ledger impact. Reconciliation should later compare provider settlement data with internal refund records.
Common Mistakes
Designing from happy-path payment approval only. The hard part is not the green path; it is retry, timeout, duplicate, reversal, settlement, and investigation.
Hiding invariants inside application code with no explicit ownership. If the rule is important, the design should name who owns it and where evidence is kept.
Letting checkout own too much financial truth. Checkout should start the customer-facing flow, but ledger, settlement, and reconciliation need stronger controls.
Treating reporting as a substitute for ledger evidence. Reports summarize; they should not quietly become the only truth.
Forgetting regional and provider differences. Currency, tax, payment methods, payout timing, and settlement files may vary.
If Someone Asks You
What requirements matter most in a commerce finance engine?
The most important requirements are the invariants: no duplicate captures, no lost refunds, traceable invoices, explainable seller payouts, correlated provider transactions, durable ledger evidence, and reconciliation between provider and internal records. Then add the controls around those invariants: authorization, audit, retention, privacy, observability, support investigation, and recovery.
What You Should Remember
The most important finance requirements are the truths that must survive retries, delays, and partial failures.
Questions to Check Understanding
What is an example of a financial invariant?
Why should checkout and ledger responsibilities be separated?
What evidence is needed for refund or seller payout investigation?