Embedded Banking SDK for B2B SaaS Platforms
Redesigning the developer onboarding experience for an embedded finance SDK, collapsing integration time from 8 weeks to 3 days, cutting integration support tickets by 72%, and unlocking $2M in new ARR.
↑ The redesigned developer portal, an interactive quickstart replacing a static PDF integration manual.
When "powerful" means "impenetrable"
Our platform offered an embedded banking SDK that let B2B SaaS companies add accounts, payments, and cards to their own products. Sales was winning contracts, but engineering teams on the partner side couldn't activate what they'd bought. The gap between "signed" and "live" was quietly killing our growth trajectory.
The root cause wasn't the underlying technology. It was the developer experience wrapped around it. Partner engineers faced unclear documentation, API-key confusion between sandbox and production, silent webhook failures, and KYB/KYC complexity they had no fintech background to interpret. We were handing them a toolbox without a manual.
An 8-week average integration time meant stalled revenue realization. 47% of developers abandoned the sandbox before their first successful API call. Support teams spent 60% of their time debugging basic partner integrations instead of higher-value work.
What I owned on this project
I was the Lead Product Designer responsible for rebuilding the developer portal end to end, from discovery and DevX testing through interaction design, platform-trust patterns, and stakeholder alignment across four different functions.
Developer Research
Unmoderated DevX testing with external pilot partners, support-ticket analysis, and a full documentation heuristic audit.
Interaction & System Design
Interactive onboarding wizard, live multi-language code samples, real-time webhook event log, environment toggle.
Platform Trust & Compliance
Designed the Production Readiness Checklist that guided non-fintech engineers safely through KYB/AML gates.
Cross-Functional Leadership
Aligned Solutions Architects, Engineering, Compliance, and Sales around a single developer-facing surface.
Three compounding failures stalling every integration
Docs assumed fintech fluency
Documentation was written for engineers who already understood banking rails. There was no "happy path" tutorial for a developer who had never touched a KYB flow before, so every integration started with a confused first hour instead of a working test call.
Sandbox and production looked identical
Test and live API keys were visually indistinguishable in the dashboard. Developers mixed them up, triggering silent authentication failures, or worse, accidentally exercising real financial side effects while "just testing."
Webhook failures were invisible
When an event failed to deliver, nothing told the developer why. They were left debugging blind, re-reading docs for clues that weren't there, until they gave up and filed a support ticket, the single biggest driver of integration support load.
How might we help a developer with zero fintech background go from first reading our docs to a live production integration in days, not months, without ever feeling lost, or exposed to compliance risk they don't understand?
If we replace static documentation with an interactive, context-aware onboarding wizard, pre-filled sandbox credentials, live executable code samples, visible webhook delivery status, and a guided compliance checklist, then developers will reach their first successful API call in minutes, and production readiness in days rather than weeks.
Watching developers fail before designing the fix
Before redesigning anything, I ran unmoderated DevX sessions with external pilot developers, watching them attempt integration with only the existing docs and onboarding flow, no coaching. That single method surfaced more than any internal review could, because internal engineers already carried the mental model we needed to design for people who didn't have.
DevX Testing
Observed external developers integrating the SDK using only the API documentation and onboarding flow, no hand-holding, no coaching.
Support Ticket Analysis
Categorised a full quarter of integration tickets. Webhook debugging and environment mix-ups accounted for the majority of the 60% of support time spent on basic integration issues.
Documentation Heuristic Audit
Audited every doc page against Nielsen's heuristics through the lens of a non-fintech engineer. Nearly every page failed "match between system and the real world."
Sandbox Funnel Analysis
Instrumented the sandbox signup flow and found 47% of developers dropped off before their first successful API call, most within the first 10 minutes.
What watching developers fail actually taught us
Developers judge an API's trustworthiness in the first five minutes
Nobody read the manual cover to cover. They copy-pasted the first code sample and watched what happened. If that sample didn't run cleanly, they judged the entire platform as unreliable, regardless of how solid the underlying API actually was.
Silent failures kill more integrations than missing features
A webhook that failed loudly, with a clear reason, was a five-minute fix. A webhook that failed silently sent developers on hour-long debugging detours and, frequently, straight to a support ticket.
Compliance felt like an opaque wall, not a guardrail
Developers didn't resent compliance requirements, they resented not knowing what was required, why, or how close they were to done. The anxiety came from ambiguity, not from the rules themselves.
The rules we designed by, and why
1 · Show, don't tell
Derived from watching developers skip long-form docs entirely and paste code straight from examples.
→ Copyable, pre-filled, live-executable code samples on every documentation page.
2 · Make failure visible immediately
Derived from support tickets showing developers debugging blind for hours after a silent webhook failure.
→ Real-time Webhook Event Log with status codes and a one-click resend.
3 · Separate exploration from consequence
Derived from environment mix-ups where identical-looking keys caused real financial side effects.
→ Hard visual and structural separation between Test and Production, via a distinct environment toggle and color language.
4 · Compliance as a checklist, not a wall
Derived from interviews where KYB/AML requirements felt opaque to non-fintech engineers.
→ A Production Readiness Checklist that names exactly what's outstanding and why, before locking production credentials.
How we validated each idea before shipping it
Each iteration targeted one of the three problems directly, tested with real external developers rather than internal engineering staff.
01 Iteration 01 · Concept Validation Paper-Prototype Testing the Quickstart Wizard
Before touching code, we walked pilot developers through a clickable prototype of the quickstart wizard, pre-filled test keys, copyable requests, a "Run Test Request" button. We measured whether they could reach a successful first API call without any facilitator help. Every session that failed pointed at a specific missing affordance, not a missing feature.
02 Iteration 02 · Failure-State Prototyping Making the Webhook Event Log Trustworthy
We simulated real webhook failure scenarios (500 errors, timeouts, signature mismatches) against a prototype event log and watched how quickly developers could diagnose and resolve each one. The addition of a one-click "Resend Event" button, tested against three alternative designs, cut diagnosis time the most decisively.
03 Iteration 03 · Language & Trust Validation Rewriting the Compliance Checklist in Plain Language
We tested the Production Readiness Checklist copy with non-fintech engineers specifically to check whether compliance language read as a partner helping them, or a wall blocking them. Early drafts read as the latter; rewriting each item as an outstanding action ("Add a webhook signature key") instead of a legal requirement ("Signature verification mandatory per policy 4.2") changed that perception directly.
The choices that shaped the outcome
Decision 01 · Live, Swagger-synced code samples vs static documentation
Tension: Live, executable examples require ongoing engineering effort to stay in sync with the real API; static docs are a one-time cost.
Choice & trade-off: We committed to live docs synced to the OpenAPI spec. The ongoing sync overhead was worth it, trust built in the first five minutes compounded directly into faster activation and more revenue.
Decision 02 · Hard sandbox/production separation vs one unified environment
Tension: Some partners wanted a single, simpler environment rather than switching contexts.
Choice & trade-off: We chose strict separation with distinct visual language. Slightly more setup friction, but it removed the possibility of a "test" action triggering a real financial consequence, non-negotiable for an embedded-finance product.
Decision 03 · Automated compliance gate vs manual review for every partner
Tension: Compliance was initially uneasy that an automated checklist would miss edge cases a human reviewer would catch.
Choice & trade-off: We shipped an automated pre-check that routes only flagged edge cases to a human reviewer. This cut review time without removing the safety net compliance needed to sign off.
A developer portal built like a product, not a manual
Every screen was designed to answer one question fast: "is this working, and if not, why?"
1. Authenticate your API
Your test API keys are pre-filled in every example. Never shared: your secret key.
↑ The quickstart wizard, pre-filled test credentials plus a live, runnable request, replacing the old static PDF manual.
↑ Real-time webhook visibility, every delivery failure shows its status code and a one-click resend.
KYB / KYC Forms
Drop-in components for identity verification.
Audit Logs
Immutable records of key generation and usage.
Granular Permissions
Keys scoped strictly to read vs. write actions.
Production Approval
Automated readiness checklist before live keys unlock.
↑ Platform-trust features that let non-fintech engineers move safely toward production.
Design doesn't happen in isolation
This redesign required deep alignment across four functions that don't naturally share a roadmap.
Engineering: keeping examples honest
I worked with engineering to sync the interactive code samples directly to the OpenAPI/Swagger spec, so the docs could never silently drift out of date with the real API.
Solutions Architects: mapping edge cases
Solutions Architects surfaced the integration edge cases (multi-entity accounts, delayed KYB approvals) that never showed up in a standard demo, but consistently derailed real partner integrations.
Compliance: vetting the automated gate
Compliance reviewed every state of the Production Readiness Checklist to make sure automation never quietly approved something a human should have caught.
Sales: turning the portal into a demo tool
I set up a feedback loop with Sales so the new portal could double as a live demo during pitches, prospects could watch a real API call succeed before signing anything.
How we arrived at the solution
Developer Experience (DevX) Testing
Observed external developers attempting to integrate the SDK using only the API documentation and our onboarding flow.
API-to-UI Mapping
Collaborated with backend architects to ensure every customizable UI component mapped precisely to a real API endpoint and permission scope.
Illustration Placeholder
Prompt: A stylized illustration of a developer-experience testing session, developers reviewing API documentation alongside a live onboarding UI on dark-mode screens, in cyan and deep-violet accent tones. Rendered as a clean illustration on a fully transparent background (no backdrop, scene, or color fill), so it displays cleanly on both light and dark page themes.
Removing friction accelerated revenue
Metrics compare the twelve months before launch against the first two full quarters after.
"We evaluated three different BaaS providers. The reason we chose this platform wasn't the pricing, it was because our engineering lead was able to spin up a test entity and make a mock transfer within an hour of finding the docs. The developer experience sold the product."
CTO, B2B SaaS Partner
Honest reflections from the process
What Worked
Testing with real external developers, not internal engineers
Internal engineers already carried the mental model we were trying to design around. Only genuine external pilot partners surfaced the confusion points that actually mattered, like environment mix-ups and silent webhook failures.
Treating documentation as a live product feature, not a shipped artifact
Syncing the interactive code samples to the OpenAPI spec meant the docs stayed honest as the API evolved, instead of quietly rotting the way static PDFs always do.
What I'd Do Differently
Bring compliance in during discovery, not after the first prototype
The automated checklist worked, but compliance's edge cases surfaced late and caused a scramble to rework flows we thought were final. Earlier involvement would have caught this in week one.
Instrument the sandbox funnel from day one
We didn't have granular step-by-step funnel analytics until partway through the project. Earlier instrumentation would have shown us the 47% drop-off point and its exact cause much sooner.