Payments Engineering
Finix Payment Integration
Owning a payments integration end to end
A full-stack Finix integration across 12+ endpoints, with a zero-PII architecture, real-time webhook processing and settlement reconciliation. Designing it meant building it first: the interface follows what the API actually permits, not what a mockup assumed.
Payments Engineering · Integration Architecture · Vendor Ownership
A payments integration has no useful mockup. The design is whatever the API's state machine permits.
Technical Scope:
- Full-stack payment processing system
- Complete Finix API integration with full PCI-adjacent compliance
- Zero-PII architecture
- Real-time webhook processing
- Settlement reconciliation systems
- PCI-adjacent compliance
Business Scope:
- Payment acceptance capability from zero
- Customer onboarding flows
- Multiple payment methods support
Standing up payment processing on our SaaS platform against strict PII compliance requirements and an integration point nobody had defined yet.
Preview Solution
The billing settings page after learning how payment processors, like Finix, actually work
A Design Dilemma
I was asked to manage the integration of a payment processor into our new, still under-development product. When I agreed, I imagined I'd be using Stripe, and I assumed it would be self-explanatory.
However, the two directives I received were:
- • No Stripe - we have a contract with Finix already in place.
- • No PII - do not store any sensitive data on our system.
To add another layer of complexity, the integration point was still undefined—the payment system could end up embedded in a website or tucked into an app's settings page.
Payment processors, like Finix, are complex ecosystems with stringent security requirements, specific workflows, and regulatory compliance needs.
I was not familiar with any of this.
Traditional design approaches would have led to beautiful mockups that were technically impossible for implementation.
I needed a fresh approach.
Discovery-Driven Development and Design
AI-Forward Approach
Design-first produces mockups nobody can build. So I flipped the order and prototyped against the live sandbox before drawing anything.
I call it Discovery-Driven Development and Design.
AI-assisted prototyping is what makes the loop tight enough to be worth running. The architecture and the compliance calls inside it were mine.
For an optional, in-depth look at the AI implementation I used on this project:
View AI Implementation Deep DiveThe traditional approach is pretty straightforward - it's the classic waterfall-ish method. Teams start by figuring out what needs to be built, study the requirements through documentation, then hand it off to designers who iterate with developers until it's shipped. It's very human-driven and sequential.
This approach reimagines how modern engineering teams operate by embracing uncertainty and allowing AI to enhance the process. Instead of front-loading exhaustive requirements gathering, we start with lightweight documentation—API schemas and executable code examples in markdown.
This documentation becomes a living interface between human intuition and AI reasoning. The AI doesn't just follow instructions; it actively participates in technical discovery, questioning assumptions, suggesting edge cases, and proposing architectures.
Once we have a working prototype—even a rough one—it becomes a shared artifact that enables true concurrent development. Designers can craft user experiences around actual functionality rather than theoretical workflows.
AI's strength isn't replacing human decision-making—it's accelerating the iteration cycles that lead to more choices and, hopefully, better decisions.
The speed of AI feedback loops enabled me to explore architectural options I never would have had time to investigate manually.
The efficiency gains were noticeable: this approach cut time to ship by approx 33%.
At the same time operating with fewer human resources, proving that speed and lean execution can coexist.
Functional Discovery
I didn't so much build the interface below, but rather coaxed it into existence.
From the very beginning of the project, I knew that the first interface I built would be temporary, more part learning tool rather than a deliverable. This freed and allowed me to focus on the functional discovery of the product.
While the official payment processor documentation covers many concepts, much of it remained more theoretical, until I started building.
The real constraints, edge cases, and UX design decisions emerged from technical reality.
I kept hitting walls when my "users" didn't map to their "identities" and my "payment methods" weren't their "payment instruments." Through trial and error, I learned each term carries precise technical and compliance implications:
- Identities (not users) — Legal entities with specific compliance requirements
- Payment Instruments (not methods) — Regulated tools with distinct capabilities
- Transfers (not transactions) — Operations with precise state tracking
- Authorizations vs Captures — Two-phase operations with different failure modes
These card components were generated directly from the Finix documentation and can be used exactly as-is in production. The structured data from the API maps cleanly to UI patterns, and the generated interfaces matched the current design system seamlessly.
Designing with System Knowledge
Once the prototype was built, it was handed off to the engineering team, including:
- • Working prototype demonstrating all core flows
- • Comprehensive documentation
- • Clear understanding of Finix certification requirements
The Result:
Engineers could focus on optimization and production hardening rather than figuring out basic integration patterns.
Meanwhile…
I could finally design with confidence. I knew exactly what data would be available and when users could expect to see it. I understood the full taxonomy of things that could go wrong. I had learned which operations happened instantly versus which ones took seconds or even days, so I could design progressive disclosure that matched reality instead of assumptions. And I deeply understood how PII constraints would shape every interaction.
Impact & Outcomes
Delivered a production-ready payment processing integration 4-6 weeks faster than traditional design-first approaches, while operating with a leaner team structure.
↗ 4-6 Weeks
faster timeline
12+ Finix endpoints integrated, with real-time webhooks and settlement reconciliation, under full PCI-adjacent compliance and a zero-PII architecture.
~33%
Faster time to ship
Created comprehensive documentation and working prototypes that enabled the engineering team to focus on optimization rather than basic integration discovery.