CH19-06: Payments, Billing, and Settlement Engine Scenario

Goal

Apply the chapter model to a cloud-native payments, billing, and settlement engine for card payments, wallet payments, refunds, invoices, seller payouts, marketplace commissions, tax, reconciliation, and finance reporting.

The Short Version

This scenario pulls the chapter together. The e-commerce company needs a finance engine that supports checkout payments, wallet payments, refunds, invoices, seller payouts, commissions, tax, chargebacks, reconciliation, support investigation, and finance reporting.

The durable idea is:

A strong finance scenario answer explains the money path, the evidence path, and the recovery path.

If the answer only says "use a payment gateway," it is too shallow. If it lists Azure services without explaining correctness, it is also too shallow. A strong answer shows how customer actions become controlled financial workflows and how the platform proves and repairs what happened.

Scenario Requirements

The marketplace has these needs:

• Customers can pay with cards and wallets.

• Orders can be authorized at checkout and captured later when fulfillment starts.

• Customers can receive full or partial refunds.

• Sellers receive payouts after fees, commissions, refunds, holds, tax, and settlement timing are applied.

• Finance needs invoices, ledger records, provider settlement reconciliation, exception handling, and reports.

• Support needs safe investigation views for payment, refund, payout, and invoice questions.

• Operations needs telemetry, alerts, replay controls, dead-letter handling, provider outage handling, and disaster recovery.

• Security and compliance teams need least privilege, audit trails, sensitive-data protection, retention, and controlled access.

Target Architecture

flowchart TB
	A["Storefront, seller portal, support tools"] --> B["Finance APIs<br/>authorize, capture, refund, invoice, payout status"]
	B --> C["Validation and controls<br/>identity, fraud, tax, limits, approvals"]
	C --> D["Durable workflows<br/>payment, refund, invoice, payout, settlement"]
	D --> E["Azure Service Bus<br/>commands, events, retries, dead-letter queues"]
	E --> F["Provider adapters<br/>card, wallet, tax, payout, settlement files"]
	D --> G["Financial records<br/>ledger, invoices, seller balances, payout batches"]
	F --> H["Reconciliation<br/>provider records vs internal records"]
	G --> H
	H --> I["Finance reports and support views"]
	D --> J["Observability, audit, and recovery"]
	K["Security controls<br/>Key Vault, managed identity, private access, RBAC"] --> B
	K --> D
	K --> G

The design starts with a finance API boundary. Storefront, seller, and support systems do not call payment providers, ledger stores, invoice systems, and payout processors directly. They send clear commands and read clear status.

Validation checks identity, authorization, request shape, amount limits, order state, fraud decision, tax inputs, seller eligibility, and business rules. Long-running financial steps move through durable workflows and messages. Provider adapters isolate differences between payment, wallet, tax, payout, and settlement providers. Ledger, invoice, seller balance, payout, settlement, and reconciliation records are stored as controlled financial evidence.

Money Path, Evidence Path, Recovery Path

Use this answer structure when explaining the design.

This structure keeps the answer practical. It also prevents the common mistake of discussing services without showing how the money is protected.

Flow 1: Checkout Authorization And Capture

At checkout, the storefront sends a payment command to the finance API. The platform creates a payment intent with an idempotency key, validates order state and amount, performs fraud and risk checks, and calls the provider adapter for authorization. The response to checkout is fast and clear.

Capture happens later, usually when fulfillment begins or the business rules allow it. A durable workflow records capture status, provider correlation, ledger evidence, and downstream events. If the provider times out, the workflow records pending or unknown status and resumes safely. It does not assume failure and issue another capture blindly.

Flow 2: Refunds, Returns, And Chargebacks

Refunds can be customer-initiated, support-initiated, or automatic after a return workflow. Every refund command needs authorization, idempotency, provider correlation, ledger impact, customer communication, and reconciliation.

Chargebacks and disputes are different from normal refunds. They might arrive from provider or network processes after the original sale. The design should route them into dispute, adjustment, ledger, support, and reporting workflows rather than treating them as ordinary checkout events.

Flow 3: Seller Payout And Settlement

Seller payout is not just "send money to seller." The payout amount may depend on order value, marketplace commission, tax, shipping, promotions, returns, refunds, disputes, seller holds, and settlement timing.

The payout workflow should calculate seller balances from controlled records, create payout batches, call payout providers, record provider correlation, and reconcile payout results. If a settlement file later shows a difference, the system should create an exception or adjustment with an owner.

Controls And Operations

The finance engine should include:

• Idempotency keys for payment, capture, refund, invoice, and payout commands.

• Provider correlation IDs and internal workflow IDs.

• Durable messages and workflows with retry, dead-letter, and replay controls.

• Ledger and invoice records that support audit and investigation.

• Reconciliation jobs that compare provider data with internal records.

• Key Vault for secrets and keys, managed identities where possible, and least-privilege access.

• Private access for supported sensitive services where required by the network model.

• Azure Monitor telemetry for APIs, workflows, queues, provider calls, ledger writes, settlement, reconciliation, and reports.

• Tested recovery paths for provider outage, delayed settlement, failed deployment, queue backlog, and regional dependency failure.

Example Two-Minute Answer

I would design the payments, billing, and settlement engine as a separate finance platform inside the e-commerce architecture. Storefront, seller, and support systems would call finance APIs rather than payment providers directly. The finance layer would validate requests, apply fraud and tax rules, and use durable workflows and messaging for capture, refund, invoice, seller payout, settlement, and reconciliation. Provider adapters would isolate card, wallet, tax, and payout integrations. Internal records would track payment intent, provider correlation, ledger entries, invoices, seller balances, payout batches, settlement files, and reconciliation results. Idempotency keys, duplicate detection, retry policies, compensation, dead-letter handling, and manual review would protect partial failures. Security would use least privilege, managed identity, Key Vault, private access where appropriate, audit logs, data minimization, and role-specific support views. Operations would monitor provider latency, queue depth, workflow state, dead-letter messages, reconciliation exceptions, and financial report health. The design protects customer experience, seller trust, finance correctness, and recovery.

Common Mistakes

• Designing only checkout payment and forgetting settlement.

• Losing provider correlation and internal financial evidence.

• Ignoring chargebacks, refunds, payouts, reconciliation, and finance support.

• Letting support tools create financial actions without idempotency and audit trails.

• Treating analytics or reporting stores as the financial source of truth.

• Failing to test replay and recovery before the first provider outage.

If Someone Asks You

Design a payments, billing, and settlement engine for a large Azure e-commerce platform.

Separate the design into finance APIs, validation, durable workflows, reliable messaging, provider adapters, financial records, reconciliation, reporting, security, observability, and recovery. Explain the money path, the evidence path, and the recovery path. The design should make payment, billing, invoice, payout, settlement, and reconciliation flows safe under retries, provider delays, partial failure, and investigation.

What You Should Remember

Explain finance architecture through state, evidence, controls, and recovery.

Questions to Check Understanding

1. Which flows are most sensitive to duplicates?

2. Which records should reconciliation compare?

3. How would you explain the money path, evidence path, and recovery path in two minutes?