# I designed the Bill Pay flow — using:

* Microservices
* Outbox pattern
* Kafka
* Batch settlement
* ISO 20022 (pain.001 / pain.002 style thinking)
* Retry + DLQ

# 1 Payment Orchestrator (Entry Point)

When a user initiates a bill payment:

**Responsibilities:**

* Validate biller
* Call Account Service → hold funds
* Insert payment row
* Insert outbox event (`state = pending`)

Why outbox?

Because we don’t want:

* DB write succeeds
* Kafka publish fails

Outbox guarantees eventual publish.

# 2 Outbox Publisher

Reads outbox table.

Publishes to Kafka topic:

`billpay.requested`

Marks outbox row as processed.

This makes the system reliable + eventually consistent.

# 3 BillPay Worker

Consumes:

`billpay.requested`

Then:

* Persists bill line
* Assigns BatchID
* Emits `billpay.enqueued`

At cutoff time:

* Emits `bill.batch.ready`

Why batching?

Real banks don’t send individual payments to clearing.  
They batch them.

# 4 Settlement Service

On `bill.batch.ready`:

* Build ISO file (pain.001 style)
* Upload to central clearing (simulated)
* On ACK → emit `bill.batch.submitted`

When clearing responds (pain.002 style):

* Parse response
* Emit `billpay.status`

# 5 Business States

Payment transitions:

Funds\_Held →  
Batched →  
Submitted →  
Posted / Failed

Funds are only fully settled when clearing confirms.

# 6 Retry & DLQ

If processing fails:

* Publish to retry topic (`bill.batch.retry`)
* After threshold → DLQ (`bill.batch.dlq`)

No silent failures.

# Design Principles Behind This

# 1. Event-driven, not synchronous chains

No service blocks waiting for another.

# 2. Funds are held early

Prevents overdraft risk.

# 3. Batch-based settlement

Mimics real clearing systems.

# 4. Outbox pattern for reliability

No dual-write problem.

# 5. Clear state machine

Payments always have deterministic state.

BILL PAY DESIGN