CH19-03: Target Architecture for Payment, Billing, Ledger, and Settlement Flows

Goal

Sketch a target Azure architecture for payment, billing, ledger, invoice, payout, settlement, reconciliation, reporting, and provider integration flows.

The Short Version

The target architecture should separate the fast customer-facing path from the slower financial correctness path. Customers, sellers, and support agents need clear responses. Finance systems also need durable workflow state, authoritative records, provider correlation, reconciliation, audit, monitoring, and recovery.

The durable idea is:

The target architecture should separate customer-facing speed from financial correctness and evidence.

Azure services are useful only when they are attached to responsibilities. For example, Azure API Management can front finance APIs, Azure Service Bus can decouple durable commands and events, Durable Functions can orchestrate long-running workflows, Key Vault can protect secrets and keys, private endpoints can keep supported service access private, and Azure Monitor can collect telemetry and support investigation. The design still starts with the money path, not with the product names.

Target Responsibility View

flowchart TB
	A["Storefront, seller portal, support tools"] --> B["Finance API boundary<br/>payment, refund, invoice, payout commands"]
	B --> C["Validation and policy<br/>identity, fraud, tax, limits, approval"]
	C --> D["Durable workflow layer<br/>capture, refund, payout, settlement orchestration"]
	D --> E["Azure Service Bus<br/>commands, events, retries, dead-letter handling"]
	D --> F["Provider adapters<br/>payment, wallet, tax, payout providers"]
	D --> G["Finance records<br/>ledger, invoice, payout, settlement"]
	G --> H["Reconciliation and reporting<br/>finance, support, audit, analytics"]
	D --> I["Observability and audit<br/>logs, metrics, traces, alerts"]
	J["Security controls<br/>Key Vault, managed identity, private access"] --> B
	J --> D
	J --> G

This is not a single mandatory implementation. It is a responsibility map. A smaller company might implement several boxes in one service. A large marketplace might split them across many services and teams. The architectural discipline is the same: keep request handling, provider calls, workflow state, records, reconciliation, and audit responsibilities visible.

Synchronous And Asynchronous Paths

Some finance decisions need a timely response. Others should move through durable workflows.

This split protects the customer experience from slow systems while still preserving financial correctness.

Azure Building Blocks

Here is a practical way to map responsibilities to Azure options:

These choices are not a checklist to copy blindly. They are a vocabulary for the architecture conversation.

Example: Authorization, Capture, Invoice, Settlement

Suppose the storefront sends a checkout request. The finance API creates an internal payment intent with an idempotency key, validates the request, and asks the payment provider for authorization. The checkout path receives a response that can be shown to the customer.

Later, fulfillment confirms that the order can ship. A durable workflow starts capture. It records workflow state, sends a command through durable messaging, calls the provider adapter, records the provider correlation, and writes internal financial evidence. Invoice generation can then use order, tax, discount, and seller data. Settlement reconciliation happens later when provider files or reports arrive. Finance compares provider records against ledger, invoice, refund, payout, and adjustment records.

If any step fails, the workflow should not vanish into logs. It should land in a visible state: pending retry, failed with reason, dead-lettered for investigation, held for manual review, or reconciled with an adjustment.

Common Mistakes

• Letting checkout call every finance system directly. That creates tight coupling and makes provider delays or finance failures visible to customers in the worst way.

• Storing only provider responses without internal financial state. Provider data is important, but the business also needs its own evidence.

• Treating reporting data as financial truth. Reporting should be downstream from controlled financial records.

• Hiding provider-specific behavior throughout the codebase. Provider adapters keep differences contained.

• Ignoring dead-letter and replay operations. Durable messaging helps only when failed messages have an owner and recovery process.

If Someone Asks You

What would a target Azure architecture for payments and settlement include?

It would include a clear finance API boundary, validation and fraud checks, durable workflows for long-running money processes, reliable messaging for decoupling, provider adapters, authoritative financial records, reconciliation and reporting paths, audit trails, secrets management, private access where needed, and observability across the whole flow. The key is to keep customer-facing speed separate from financial evidence and recovery.

What You Should Remember

Finance systems need clear APIs, durable workflows, authoritative records, reconciliation, and audit trails.

Questions to Check Understanding

1. Which finance flows should be asynchronous?

2. Why does the system need internal state in addition to provider responses?

3. Where should reconciliation data fit in relation to ledger and reporting records?