FinTech Infrastructure

VCN Platform

Virtual card infrastructure for controlled spend, partner integration, and reconciliation-aware operations.

Controlled spend Webhook-safe lifecycle tracking

Context

This was designed as a real financial infrastructure product rather than a thin API wrapper. The system had to support shopper-facing issuance flows, admin controls, partner subscription handling, reconciliation checks, and event-driven updates from banking partners while keeping the first version understandable and safe to operate.

Problem

Teams needed a reliable way to generate and manage virtual card numbers for shopper operations without relying on manual handoffs, spreadsheet state, or loosely enforced controls. The system had to support card generation, weekly usage rules, spending limits, region restrictions, admin overrides, partner integration, and future multi-tenant growth without jumping straight to heavyweight distributed architecture.

What I Built

Backend services and relational models for users, cards, vault references, partner subscriptions, transaction events, webhook events, and admin actions
User and admin issuance flows with region-aware controls, weekly limits, spend thresholds, and override paths
Webhook ingestion layer for card lifecycle and transaction updates with append-only event storage before state mutation
Normalization and reconciliation logic to compare internal card state with partner-reported transaction and status events
Operational views designed around auditability, event traceability, and clean debugging paths rather than only happy-path API responses

Notes

Context

The core product problem was controlled spend in an environment where card issuance and transaction state needed to be trustworthy. A VCN system has to do more than create numbers. It has to preserve guardrails, support operator overrides, ingest asynchronous partner events safely, and give downstream teams enough visibility to explain what happened when something looks wrong.

Technical design

The architecture deliberately stayed database-centered. The product needed explicit state transitions, not premature infrastructure. I modeled cards, users, partner subscriptions, webhook events, transaction snapshots, and admin actions as first-class entities so the operational story was visible in the data model itself.

The webhook layer was treated as an append-only event boundary. Raw events are worth keeping because duplicate deliveries, out-of-order partner updates, and signature failures become much easier to debug when the original payload and processing outcome remain visible.

Concurrency and correctness

The system had to assume retries and duplicates. That shaped several design decisions:

idempotent handling for partner events
careful transaction boundaries around card state changes
row-level concurrency awareness when the same card could receive multiple status or transaction updates close together
reconciliation workflows to catch drift instead of pretending drift would never happen

That is a more realistic shape for financial software. Real systems are not judged by how clean the happy path looks. They are judged by how quickly teams can trust the state after something surprising happens.

The project reinforced a set of engineering instincts that still hold up for me: model the domain explicitly, keep state transitions visible, and choose the simplest architecture that remains trustworthy when events arrive out of order or systems disagree.

Role / ownership

Owned backend system design and domain modeling for issuance, control logic, and partner event handling
Drove the shape of the relational schema and the operational model for debugging and reconciliation
Focused on balancing fintech correctness with a v1 architecture the team could reason about and extend

Impact

Turned a brittle manual coordination problem into a structured card-issuance and lifecycle platform with explicit controls, cleaner auditability, and a path to multi-partner scale.

Stack

FastAPI
Python
SQLAlchemy
PostgreSQL
Webhooks
Event Processing
System Design

Technical design

FastAPI service layer organized around explicit card, user, partner, and event domains
PostgreSQL schema modeled for lifecycle traceability with normalized entities for cards, controls, partner subscriptions, webhook events, and transaction snapshots
SQLAlchemy ORM with transaction boundaries designed around predictable state changes and future migration discipline
Webhook verification and normalization layer that stores raw partner payloads before applying domain-specific handlers
Reconciliation jobs that compare expected internal state with partner state and surface mismatches for review

Engineering decisions

Kept v1 synchronous and database-centered instead of introducing queues too early, because the product needed clarity and auditability more than distributed complexity
Stored webhook events append-only before mutating card state so duplicates, retries, and partner-side anomalies remained inspectable
Designed explicit state transitions for card lifecycle events rather than treating partner updates as direct overwrites
Treated sensitive card data conservatively by limiting what the platform stores directly and modeling vault references separately from business state
Planned for future multi-tenancy through clean domain boundaries and partner abstractions without forcing a heavy tenant-isolation model into the first release

Tradeoffs

A queue-backed architecture may eventually help at larger scale, but adding it too early would have made event handling harder to audit in the first version
Strict control logic improves safety, though it increases the number of admin exceptions and override paths that need careful modeling
Keeping reconciliation close to the product model improves trust, but it requires more deliberate schema design than a thin partner proxy would

Outcome / impact

Reduced manual coordination around issuance and card-control management
Created a clearer operational model for card state, partner updates, and finance-facing reconciliation questions
Improved readiness for multiple partner integrations because the core lifecycle and event model were not hard-coded to one vendor's surface behavior

Lessons learned

In financial systems, correctness starts with domain modeling rather than monitoring added later
Webhooks are not just notifications; they are distributed state transitions that need idempotency and traceability
The right first architecture is often the one that is easiest to audit under failure, not the one with the most infrastructure