Payment Orchestration Platform
A reference implementation for multi-provider payment flows, retries, reconciliation, and operator visibility.
Designed as a realistic internal payments platform that routes transaction intents through multiple PSP connectors while keeping idempotency, auditability, and operational control first-class.
Project context
This is a portfolio reference implementation built to demonstrate payment-systems design, not a description of employer production work. It was designed to show the kind of internal orchestration platform a fintech team could use to keep provider integrations from leaking complexity across the product. Instead of treating each PSP as a one-off implementation, the system centers on stable internal payment contracts, provider adapters, resilient webhook handling, and reconciliation support for operations.
Core services
6
Transaction states
14
Recovery model
Retry plus DLQ
Role and positioning
Architecture, backend design, integration modeling, operational UX
Strong signal for fintech and backend platform roles that need domain depth beyond generic CRUD services.
Payment teams rarely struggle with a single happy-path authorization call. They struggle with duplicated requests, asynchronous provider behavior, webhook races, settlement mismatches, partial failures, and the long tail of states that support teams need to understand later.
If those concerns are spread across product services, every new provider becomes slower to integrate and harder to operate. The platform needed a stable orchestration layer that could accept transaction intents once, enforce idempotency, route requests consistently, and preserve a full audit trail regardless of provider-specific behavior.
I modeled the platform around a dedicated transaction service that owns the internal state machine and emits domain events for downstream processing. Provider connectors sit behind a narrow capability contract so routing and retry logic stay centralized instead of fragmenting across integrations.
Webhook ingestion is treated as an equally important path rather than an afterthought. Incoming provider callbacks are normalized, deduplicated, and correlated back to internal transaction state before any side effects are applied.
To make the project portfolio-grade rather than purely academic, I added the operator layer as well: a reconciliation view, searchable audit trail, and admin-facing timeline that makes it easier to understand why a payment is in its current state.
Structured to separate core domain responsibility from provider or workflow-specific complexity.
The architecture separates payment intent intake, transaction state ownership, provider integration, asynchronous webhook handling, and operational insight into clear boundaries that can evolve independently.
Sample auth p95
182 ms
Sample queue depth
12
Sample mismatches
2
Illustrative transaction timeline
reconciliation-readyIntent received
Idempotency key validated
Connector selected
Provider B routed after fallback rule
Webhook matched
Authorization confirmed and persisted
Settlement batch
Awaiting daily reconciliation
Illustrative connector health
API Gateway and Merchant API
Receives payment intents, validates contracts, enforces idempotency key rules, and exposes stable internal APIs to the rest of the product.
Transaction Orchestrator
Owns the state machine, routes provider calls, records lifecycle transitions, and publishes payment domain events.
Provider Connector Layer
Implements PSP-specific authentication, payload mapping, error normalization, and timeout policies behind a shared adapter interface.
Webhook and Event Processing
Accepts asynchronous provider callbacks, deduplicates events, and reconciles external status updates with internal transaction state.
Reconciliation and Operations Surface
Exposes dashboards, audit trails, failed delivery queues, and settlement mismatch visibility for support and finance workflows.
Idempotency at the platform edge
The API layer stores request fingerprints and idempotency results so duplicate requests never reach downstream provider connectors unnecessarily.
Connector contracts stay narrow
Provider adapters expose only the capabilities the orchestration layer needs, which makes adding new PSPs less invasive and easier to test.
Webhook paths are stateful, not append-only
Provider callbacks update authoritative transaction history through the same lifecycle model used by synchronous requests, keeping the state machine coherent.
Features and operational views that make the reference implementation feel credible beyond the API layer.
The point is to show backend depth alongside the operator-facing surfaces real teams need in order to diagnose and run a system well.
Provider abstraction with routing rules
Supports multiple PSP connectors behind a common internal contract, including rule-based fallback and capability-driven routing.
Idempotency and state protection
Enforces idempotency keys at the edge, stores request fingerprints, and prevents duplicate transaction creation under retry pressure.
Webhook ingestion pipeline
Normalizes asynchronous provider events, guards against duplicates, and applies correlated state transitions with an explicit audit trail.
Retry, dead-letter, and recovery handling
Separates transient connector issues from terminal failures and exposes dead-letter visibility for operational follow-up.
Reconciliation and audit support
Includes daily reconciliation summaries, transaction search, and event timelines that mirror how support and finance teams investigate incidents.
Operations cockpit
A transaction timeline with provider state, retry history, webhook events, and current reconciliation posture.
Connector health surface
Provider latency, error buckets, dead-letter counts, and recent routing decisions for operational review.
Reconciliation workspace
Daily summaries that highlight settled, pending, mismatched, and manually reviewed payment batches.
- A centralized orchestration model improves consistency but creates a critical platform dependency. The design compensates with clear service ownership, observability, and explicit failure handling.
- Connector abstraction reduces integration sprawl, but forcing every provider into the same model can hide meaningful differences. The contract intentionally leaves room for provider-specific capabilities without contaminating the core domain.
- Reconciliation logic inside the platform increases scope, yet it is often the layer that proves whether a payment system is operationally mature. I treated it as part of the real product rather than a reporting afterthought.
- Shows credible payment systems thinking across synchronous and asynchronous flows, not just API wrapping.
- Demonstrates how internal platform design can lower the cost of adding or switching PSPs over time.
- Creates visible proof of backend maturity for recruiters evaluating fintech, payments, and platform engineering fit.
- Add rule-based routing informed by cost, region, and historical provider performance.
- Implement load-test profiles and publish throughput baselines for authorization and webhook workloads.
- Extend the admin UI with manual recovery actions and approval logging for high-risk operations.
- apps/admin-ui for the operator interface and reconciliation views
- services/transaction-service for the internal payment state machine
- services/provider-connectors for PSP adapter implementations
- services/webhook-ingestion for callback normalization and event correlation
- platform/local-stack for Docker, local dependencies, and observability tooling