Payabli is a next-generation payments infrastructure and monetization platform that provides comprehensive payment processing solutions centered around what we call the Three Ps: Pay In, Pay Out, and Pay Ops. With complex APIs supporting everything from ACH processing to vendor management, Payabli's documentation services developers working with sophisticated payment workflows.
This article is written by Casey Smith, who is Payabli's Head of Technical Writing.
The API specification management bottleneck
Like other fast-moving companies, some of our APIs were developed iteratively based on customer requirements rather than predetermined designs. The complexity of our payment APIs made our API spec management a frequent source of friction. Some of our endpoints include dozens of conditional fields based on things like payment method, merchant service type, and other factors. We exhausted OpenAPI's capabilities and had to get creative with workarounds to get basic docs published.
This overhead wasn't just costing us time, but it also kept us from doing more with our docs. When documentation teams spend most of their energy on maintenance rather than crafting useful docs, the developer experience suffers. We couldn't innovate and we couldn't build new developer resources.
We needed a tool that would let us:
- Write and manage our API definition more efficiently
- Add interactive features to the docs with custom React components to help break down complex topics
- Single-source content to build our API references, Postman collections, SDKs, and code examples without manual interventions and updates
- Have a slick doc site that's on-brand and easy to maintain and gives us complete control over the navigation and organization
We looked at every docs solution out there, but Fern ultimately was the only one that checked all the boxes.
OpenAPI vs Fern Definition: Major time savings in real-world use
Fern Definition, an alternative to OpenAPI Specification for describing APIs, changed the game for our documentation workflow. The definition's flexibility and design philosophy made it far easier to accurately represent our complex payment APIs without the friction we'd experienced before. Fern Definition solved two pain points for us: the clean type aliasing syntax made our spec more readable, and the elegant union support eliminated OpenAPI's cumbersome oneOf / anyOf patterns. These ergonomic improvements are what made us fall in love.
Using the OpenAPI specification to describe our APIs always felt like trying to force a square peg into a round hole. Fern Definition is intuitive enough that new team members can contribute quickly and our complex data models don't require workarounds to describe accurately. Fern Definition feels like it was made to describe our APIs.
The results of adopting the Fern Definition were immediate and dramatic: the percent of our team effort spent doing spec management dropped from ~30% to roughly ~5%. This 80% reduction freed up our team to focus on creating better developer experiences rather than fighting with tooling. We've even had to recalibrate how we assign effort points to tickets because of how much Fern Definition had streamlined our API management.
We got a perfect test case for this improvement when substantial API changes required us to refactor documentation for a route with 8 endpoints—the same scope of updates we'd done for the same endpoints last year with OpenAPI. Using our detailed time tracking, we discovered that the refactor work that took us 4 hours last year took just 38 minutes with Fern Definition. Whether it's new endpoints, customer-requested named examples, new fields, or response schema changes, the same number of tickets now requires dramatically less effort from our team.
The time saved on spec maintenance has let us explore adding new interactive developer tools.
Interactive developer tools beyond basic docs
One of our biggest gains from moving to Fern has been using custom components to create interactive documentation features. Custom React component support isn't universal across doc tool vendors, and we were forced to build a few free-standing developer tools hosted outside of our docs before using Fern. This quickly became unwieldy, and we wanted a solution that would let us bring more functionality and value into our documentation. Fern's custom component support has enabled us to build genuinely useful tools that help developers understand complex concepts.
Our documentation now includes features such as:
- Transaction lifecycle explorer: An interactive guide that walks readers through the complete payment transaction process and explains the complex interplay of various statuses
- ACH timeline calculator: A dynamic calculator that helps readers understand ACH processing timelines for different scenarios
- Embedded component demos: Live demonstrations of embedded payment components, so developers can see a component in action without any effort
- Code walkthroughs: Step-by-step interactive code walkthroughs for complex implementations
These interactive elements help our readers better understand complicated concepts and experience features in the docs, giving them a holistic understanding of our products and the payments industry. Abstract concepts like transaction lifecycles and settlement timelines are easier to understand when readers can interact with them through our components.
Single-source documentation: one definition, four outputs
Our 2-person documentation team is most excited about how Fern enabled us to maximize our impact without adding headcount. Fern has made it frictionless to single-source many of our developer resources from our API definition to create a web of resources that stay in sync automatically.
From our Fern Definition files, we generate:
- A complete API reference
- Postman collections for testing
- SDKs in 7 languages
- Code examples throughout our developer guides
This single-source approach eliminates the headaches that plague many documentation teams, where API changes require a writer to make manual updates across multiple systems and formats.
Styling and navigation control for API documentation
For us, choosing Fern wasn't just about current capabilities, it was about future scalability. Their approach to custom styling and navigation control made it clear that we could grow our documentation and represent the Payabli brand without hitting arbitrary limitations or worrying about design instability.
Custom CSS
We saw Fern as a platform to grow on because of their styling approach. With doc tools we'd used in the past, custom CSS support always felt like an afterthought, and we struggled to brand our site, and often dealt with unexpected updates that impacted our site's look and functionality.
Fern provides first-class custom CSS support with dozens of thoughtful, stable CSS selectors that let us dial in our doc site's look and feel to match our brand. They treat updates that would affect custom styling as breaking changes, so we can relax and know that Fern isn't going to push something that would make our marketing team sweat and leave our team scrambling to update our custom styles.
Navigation configuration
The navigation control has been particularly valuable for organizing our 212 documented endpoints. Unlike many API reference generators that automatically group content by route or tag with no override options, Fern's approach lets us craft the information architecture that best serves our developers' workflows.
Better docs, better developer productivity
The combination of better spec management, interactive features, and single-source consistency has created a compound effect for our developer experience. When documentation is easier to maintain, more accurate, and more engaging, developers spend less time confused and more time successfully integrating.
Our docs team spends less time fighting tooling and more time creating useful content and developer enablement tools. This sets us up to scale and moves us closer to our goal of being the easiest payments company to integrate with.
This efficiency gain allowed us to build 6 high-value custom components in our first 6 weeks with Fern, giving our readers new interactive tools that were previously impossible for us to prioritize. We've also been able to start working on more deep dive guides and quickstarts, the kind of developer enablement content that actually moves the needle but was always pushed aside by maintenance work.
This translates directly to better developer productivity and faster feature adoption—critical metrics for any company offering complex technical products like payment processing APIs.
Key results:
- 80% reduction in spec management time
- 6 interactive components built in 6 weeks
Since adopting Fern, we've been able to create the kind of documentation experience that our developers need and want to use. When you don’t have to fight your tools, you can focus on what matters. The right documentation tooling can 10x your team. By reducing spec management overhead by 80%, enabling rich interactive features, tight navigation and styling controls, and providing single-source consistency across all developer resources, Fern has enabled us to focus on creating documentation that genuinely helps developers succeed.
Oh, and if you’re curious what that looks like, grab a coffee and take a look: docs.payabli.com
.avif)
.jpeg)
