CH19-01: Payments, Billing, and Settlement Mental Model

Goal

Build the starting mental model for a commerce finance engine. The reader should see payments, billing, settlement, reconciliation, and reporting as controlled financial state changes, not as one successful call to a payment provider.

The Short Version

When a customer checks out, the visible experience feels simple: choose a product, pay, receive confirmation, wait for delivery. Behind that moment, the platform has to coordinate several responsibilities that happen at different times and have different evidence requirements.

A payment can be authorized before money is captured. Capture might happen after fulfillment begins. A refund can be requested by a customer, a support agent, or an automated return flow. A seller payout might happen days later after fees, tax, commissions, returns, and settlement rules are applied. Finance teams still need to reconcile provider settlement files with internal records after the customer has already moved on.

The durable idea is simple:

Money-related workflows need proof, not only successful API responses.

The system has to prove what was requested, what was approved, what changed, what failed, what was retried, what was reversed, and what was finally reconciled. That proof matters to customers, sellers, support agents, finance teams, auditors, and operations teams.

The Mental Model

Think of the finance engine as five connected paths:

flowchart LR
    A["Customer, seller, or marketplace action"] --> B["Finance APIs<br/>payment, billing, refund, payout"]
    B --> C["Validation<br/>fraud, tax, authorization rules"]
    C --> D["Durable financial workflows<br/>capture, invoice, refund, payout"]
    D --> E["Financial records<br/>ledger, invoice, settlement, reconciliation"]
    E --> F["Evidence and reporting<br/>support, finance, audit, operations"]

Each path has a different job:

Responsibility	Plain-language job	Why it matters
Payment	Ask a provider to authorize, capture, void, or refund money.	Provider state must be correlated with internal state.
Billing and invoice	Explain what the customer, seller, or marketplace owes or receives.	The business needs a durable commercial record.
Ledger evidence	Record financial facts in a controlled way.	Reports and investigations should not depend only on provider responses.
Settlement	Match provider, bank, seller, tax, and internal records after money movement.	Money often settles later than the customer action.
Reconciliation	Find and explain differences between systems.	Differences should become visible before they become finance incidents.

You do not need to master finance terminology all at once. For architecture, the key is to separate responsibilities. Checkout is a customer interaction. Provider integration is an external dependency. Ledger evidence is internal proof. Settlement and reconciliation are later control loops. Reporting is how finance and operations explain what happened.

Why The Provider Call Is Not Enough

A payment provider is essential, but it is not the whole system. The provider can tell you whether a specific authorization, capture, refund, or payout request was accepted or rejected. It cannot own your full commerce state.

Your platform still needs to know:

Which order, invoice, seller, customer, tax rule, promotion, shipment, or return caused the financial action.
Whether the request was already attempted and what result is safe to return if the caller retries.
Whether a provider timeout means the operation failed, succeeded, or is still unknown.
Which internal records should be updated when settlement files arrive later.
Which evidence support and finance teams need when a customer asks, "Where is my refund?"

That is why a strong design separates the fast customer path from the slower evidence and settlement paths. The customer should receive a clear response, but the platform must also keep enough durable state to investigate, recover, and reconcile.

Example: One Order, Many Finance Moments

Imagine a customer buys a laptop from a marketplace seller.

At checkout, the platform creates a payment intent and asks the provider for authorization. Authorization means the payment method appears usable and funds may be reserved, but it is not the same as final settlement. The order service records that checkout can continue.

When fulfillment starts, the platform captures the payment. Capture is a separate financial action and needs its own request identity, provider correlation, status, and evidence. The marketplace calculates commission, taxes, seller receivable amounts, and invoice data. Later, the provider sends settlement information. Finance compares that settlement against internal ledger records, invoices, refunds, chargebacks, and seller payout records.

If the customer returns the laptop, the refund path begins. A support agent might retry after a timeout. The system must not create two refunds just because the first response was unclear. It should return the known result or continue the same refund operation safely.

This is why commerce finance architecture is really a trust architecture. It protects trust between the customer, seller, marketplace, finance team, provider, and support organization.

Common Mistakes

Treating payment approval as financial correctness. Approval is one event; correctness also depends on internal records, capture, refunds, settlement, reconciliation, and reporting.
Mixing checkout state, provider state, ledger state, and reporting state into one vague record. That makes recovery and investigation difficult.
Forgetting that settlement happens later. A system can look healthy during checkout and still have finance differences after provider files arrive.
Letting support tools perform financial actions without idempotency, audit trails, or authorization boundaries.
Designing reports as the source of truth. Reports should explain financial records; they should not quietly become the only place where financial truth exists.

If Someone Asks You

How should I think about payments and settlement architecture?

Think of it as controlled financial state change. Checkout starts the journey, but the architecture must also separate provider integration, fraud checks, billing, invoices, ledger evidence, settlement, reconciliation, support investigation, and reporting. The design should prove what happened, make retries safe, expose differences, and support recovery when providers or internal steps fail.

What You Should Remember

Finance architecture must explain what happened, what changed, and how the system can prove it.

Questions to Check Understanding

Which responsibilities are separate from a payment provider call?
Why can checkout succeed before settlement is complete?
What evidence might support, finance, or audit teams need when investigating a refund or payout?