Payments and Settlement Scenario

Goal

Close the chapter with one complete commerce scenario. The design must show the money path, evidence path, and recovery path under peak traffic and partial failure.

The durable idea is:

A useful financial scenario shows how controlled transitions, evidence, retries, and recovery work together under real pressure.

Scenario

A multi-seller marketplace is preparing for a holiday sale. It supports cards and digital wallets, authorization at checkout, capture when fulfillment begins, full and partial refunds, invoices, marketplace fees, seller payouts, disputes, provider settlement files, and finance reporting.

The sale creates several risks at once:

• Customers refresh or resubmit checkout when responses are slow.

• The payment provider sometimes accepts a command before its response times out.

• Fulfillment can split one order across warehouses and dates.

• Refunds may be initiated by returns workflows or support agents.

• Seller payouts depend on fees, tax, returns, disputes, holds, and settlement timing.

• Provider settlement records arrive later and occasionally contain duplicates or corrections.

• Finance and support need safe investigation paths during the event.

The architecture must remain provider-neutral. Services can be selected later; first make the responsibilities and invariants visible.

Target Responsibility View

flowchart TB
    A["Storefront, seller portal, support tools"] --> B["Finance API boundary<br/>authorize, capture, refund, status"]
    B --> C["Validation and policy<br/>identity, amount, order state, risk, approvals"]
    C --> D["Durable financial workflows<br/>payment, refund, invoice, payout"]
    D --> E["Provider adapters<br/>card, wallet, tax, payout"]
    D --> F["Financial records<br/>operations, ledger, invoice, seller balance"]
    E --> G["Provider callbacks and settlement records"]
    F --> H["Reconciliation and exception handling"]
    G --> H
    H --> I["Finance, support, audit, and reporting views"]

    J["Identity, data protection, audit, observability, recovery"] -.-> B
    J -.-> D
    J -.-> F
    J -.-> H

The finance API is a boundary, not a thin proxy. Storefront, support, and seller systems do not call providers or write financial records directly. They submit authorized commands with stable operation IDs and read explicit status.

Provider adapters isolate external protocols and failure semantics. Durable workflows make multi-step progress and exceptions visible. Financial records protect internal truth. Reconciliation compares that truth with independent provider and settlement evidence.

The Three Paths

A concise architecture explanation should cover three paths.

If a design explains only the money path, it will look convincing until the first ambiguous timeout.

Phase 1: Authorization At Checkout

The storefront sends an authorization command containing an order reference, amount, currency, customer payment token or provider reference, and a stable idempotency key. The finance boundary authenticates the caller, validates the command, checks that the order and amount are eligible, and applies risk and policy decisions.

The payment workflow records the operation before calling the provider. If the customer refreshes, the repeated command resolves to the same operation. A key reused with a different amount is rejected.

The provider returns one of four meaningful outcomes:

• Confirmed: authorization succeeded and provider correlation is recorded.

• Rejected: authorization did not succeed and the reason is classified safely.

• Pending: the provider explicitly reports work in progress.

• Unknown: the request may have completed but confirmation was lost.

Checkout receives a response appropriate to that state. Unknown is not translated into a fresh attempt under a new identity.

Phase 2: Split Fulfillment And Capture

The order is split across two warehouses. The business has decided to capture against fulfillment milestones rather than capture the entire order immediately. That rule needs an explicit model: the platform must know which amount is eligible, how partial captures relate to the original authorization, and how the total is constrained.

Each capture is a controlled operation with:

• A unique but stable capture ID.

• The parent authorization and order references.

• The fulfillment milestone that permitted it.

• Amount, currency, and cumulative-limit checks.

• Provider correlation and state history.

• Ledger and invoice consequences.

The first capture succeeds. The second provider call times out after submission. The workflow records capture_unknown, stops automatic creation of another capture for the same fulfillment milestone, and queries the provider using the correlation. A circuit breaker reduces pressure while the provider is degraded.

When confirmation arrives, the workflow advances from the durable checkpoint. If confirmation cannot be obtained within the defined time, the case moves to finance operations with the evidence needed to investigate.

Phase 3: Billing, Ledger, And Seller Position

Billing creates an explainable invoice from order lines, tax inputs, discounts, shipping, and marketplace fees. The ledger records the accepted financial facts according to the organization's model. Seller balances are calculated from controlled records rather than from storefront display state.

These responsibilities do not all block checkout. They progress asynchronously, but their dependencies are explicit. An invoice or payout cannot quietly assume a capture that is still unknown. A correction creates a new governed adjustment instead of rewriting history.

For the marketplace, the seller's payout position includes:

eligible captured sales
  - marketplace commission
  - refunds and disputes
  - tax or withholding obligations
  - seller holds and reserves
  + approved adjustments
  = payout candidate

The formula is a business example, not a universal accounting rule. Its architecture purpose is to show that a payout needs versioned inputs, ownership, and evidence.

Phase 4: Refund During Provider Degradation

A customer returns one item. Support approves a partial refund. The support tool can submit the approved refund and view status, but it cannot edit ledger records or bypass amount limits.

The refund command uses a stable ID tied to the return and approval. The provider times out. The support agent refreshes twice, yet the idempotency layer returns the existing refund_unknown operation. The workflow queries rather than blindly repeating the side effect.

If fulfillment or invoicing has already progressed, the refund triggers controlled downstream credit and adjustment work. That work may be eventually consistent, but it is visible through workflow states and must converge through reconciliation.

Phase 5: Settlement, Payout, And Reconciliation

The provider delivers a settlement file after the sale. Ingestion validates source, format, file identity, sequence, and record integrity. Duplicate files and duplicate rows do not create duplicate settlement results.

Reconciliation compares:

• Authorizations, captures, refunds, and disputes.

• Provider correlations and settlement records.

• Ledger and invoice evidence.

• Seller balances and payout batches.

• Amounts, currencies, dates, fees, and record types.

Results become matched, pending, or exception. One provider record shows the second capture, resolving the earlier unknown outcome. Another row has a currency mismatch and becomes an exception with an owner, age, materiality, and resolution deadline.

Seller payout finalization uses only the states and evidence the business has approved. A missing or materially inconsistent settlement record can hold the affected payout without stopping unrelated sellers.

The Incident Timeline

sequenceDiagram
    participant S as Storefront
    participant F as Finance platform
    participant P as Payment provider
    participant R as Financial records
    participant X as Reconciliation
    participant O as Finance operations

    S->>F: Capture CAP-4815
    F->>R: Record operation pending
    F->>P: Submit capture with correlation
    P--xF: Response lost after acceptance
    F->>R: Mark capture unknown
    F->>P: Query existing operation
    P-->>F: Temporarily unavailable
    F->>O: Alert with operation evidence
    P-->>X: Later settlement record
    R-->>X: Internal operation and ledger evidence
    X->>R: Confirm matched capture
    X->>O: Open separate currency-mismatch exception

This timeline reveals why idempotency, evidence, and reconciliation are one design. No component alone can guarantee the final answer across an independent provider boundary.

Operating Model

The solution is complete only when humans can operate it.

Runbooks cover provider degradation, capture uncertainty, refund backlog, missing settlement, reconciliation differences, replay approval, and recovery after data or regional failure. Dashboards connect technical signals to affected operations and amounts.

Architecture Review Summary

A strong review can now answer:

• Boundaries: Payment, billing, ledger, settlement, and reconciliation protect different truths.

• Invariants: Duplicate captures and refunds are prevented; corrections remain traceable.

• Timing: Checkout is fast, while durable finance work and reconciliation continue safely.

• Failure: Unknown outcomes pause, query, escalate, compensate, or reconcile according to state.

• Controls: Identity, least privilege, data protection, audit, and approvals surround every action.

• Operations: Business telemetry, exception ownership, runbooks, and tested recovery make the design supportable.

Common Mistakes

• Drawing only the successful authorize-and-capture path.

• Treating every fulfillment event as permission to capture without cumulative amount and state checks.

• Allowing support retries to create new refund identities.

• Calculating seller payout from storefront or reporting data instead of controlled financial evidence.

• Treating settlement ingestion as trusted merely because the file came from a known partner.

• Marking the incident resolved when the provider recovers but before reconciliation closes uncertainty.

• Listing services without explaining the money, evidence, and recovery paths.

If Someone Asks You

What should a payments scenario prove to the reader?

A good answer is:

It should prove the money path, evidence path, and recovery path. I would show controlled authorization, capture, refund, billing, ledger, settlement, and payout responsibilities; stable operation IDs and provider correlation; durable workflow state; explicit unknown outcomes; compensation and reconciliation; scoped operator access; and tested recovery. The final state must be explainable even after retries and partial failure.

What You Should Remember

Finance scenarios should show controlled change under pressure.

Questions to Check Understanding

1. Which invariants protect split capture and partial refund flows?

2. Why should an unknown provider outcome block a fresh financial operation but not necessarily the entire platform?

3. What evidence lets reconciliation close the incident confidently?

Further Study

• Compensating Transaction pattern - Review recovery considerations for multi-step operations that cannot use one distributed transaction.

• NIST SP 800-34 Rev. 1: Contingency Planning Guide for Federal Information Systems - Use the planning and testing lifecycle to deepen the scenario's recovery design.