Building the docs and the API at the same time
Most API documentation projects start with a working API. A developer builds it, hands it over, and a technical writer documents what exists. Payrail was built differently — the API and the documentation were developed together, with the documentation driving decisions about how the API should behave.
Payrail is a fintech payments REST API covering customers, payment methods, transactions, and refunds. It exists for two reasons: as a learning project to develop hands-on experience with API architecture and developer documentation, and as a portfolio piece demonstrating what a technical writer can produce when given full ownership of a developer-facing product.
The problem it solves
Fintech APIs are among the most documentation-dependent products in software. A payments integration is not something a developer can figure out by trial and error — the stakes are too high. Missing an idempotency key means duplicate charges. Skipping signature verification means your webhook endpoint accepts spoofed requests. Getting the amount format wrong means charging $150 instead of $1.50.
Payrail was designed to document exactly these kinds of decisions — not just what the endpoints do, but why they work the way they do and what goes wrong if you get it wrong.
What was built
The API is a Node.js REST API with five resource types: auth, customers, payment methods, transactions, and refunds. It implements JWT authentication, idempotency key handling, rate limiting, and webhook delivery with HMAC-SHA256 signature signing.
The documentation is a Docusaurus site covering a quickstart guide, full API reference, authentication, payment workflow, webhooks, data models, versioning, error codes, code examples in curl, JavaScript, and Python, an FAQ, and three end-to-end tutorials.
The AI documentation assistant is a RAG-powered chat widget embedded on every page of the documentation site. It is built on the same architecture as the Material Specs KB project — documentation markdown files are chunked, embedded using OpenAI’s text-embedding-3-small model, and stored in a Pinecone vector index. When a developer asks a question, the widget POSTs to a Flask API hosted on Render, which retrieves the top three matching chunks and passes them as context to GPT-3.5-turbo. The answer appears inline without leaving the docs. A local search plugin provides keyword search as a complement to the AI assistant — a keyword search answers “where is the webhooks page” while the AI assistant answers “how do I verify a webhook signature in Python.”
The live API is deployed on Render. The documentation site is hosted on GitHub Pages.
Technical decisions
Docusaurus for documentation Docusaurus is free, open source, and widely used by developer tools companies including Meta, Shopify, and Vercel. For a technical writer building an API documentation portfolio, it is the right tool — it produces the kind of docs a developer would actually expect to see, and it demonstrates familiarity with a real industry-standard toolchain.
A fictional API rather than documenting a real one The decision to build a fictional API rather than document an existing public API like Stripe or Twilio was deliberate. Real APIs have real data and real consequences. A fictional fintech API allows full control over the design, the edge cases, and the documentation decisions — including the ability to intentionally add complexity like webhook signing and idempotency keys that are worth documenting carefully.
Node.js for the backend Node.js was chosen for the backend because it is the dominant language in the API tooling ecosystem. Understanding the runtime that most API developers work in makes it easier to write accurate, credible documentation.
JWT authentication over API keys API keys are simpler to implement and document, but JWT is the more common pattern in production fintech systems. Choosing JWT meant learning how token expiry, bearer headers, and authentication middleware actually work — which produces better documentation than describing something you haven’t implemented.
Building webhook signing rather than leaving it aspirational The original webhooks page documented signature verification without the API actually implementing it. The decision to build the feature properly — HMAC-SHA256 signing, delivery on status change, retry logging — came from a simple principle: document what exists, not what you plan to build. A developer who reads the docs and finds the feature doesn’t work loses trust in everything else.
AI assistant over static search alone A keyword search plugin answers “where is the webhooks page.” An AI assistant answers “how do I verify a webhook signature in Python.” Both are useful for different questions, so both are included. The AI assistant uses the same RAG pipeline pattern as the Material Specs KB project — a deliberate decision to apply a proven architecture to a new use case rather than learn a new tool.
Results
The documentation covers every endpoint with request parameters, response schemas, error codes, and code examples. The webhook implementation is fully functional — a status update to a transaction fires a signed POST request to a registered endpoint, verifiable in real time using webhook.site.
The three tutorials cover the complete developer journey: processing a first payment, handling a failed transaction and retry, and verifying a webhook signature end-to-end.
The AI assistant answers questions about the API directly from the documentation, without leaving the docs site.
What I’d do differently
Docusaurus deployment has multiple configuration paths, and the right one depends on your hosting setup. Debugging deployment issues — broken links, build errors, GitHub Pages configuration — consumed more time than building the documentation itself. Starting with a clearer deployment strategy upfront would have saved several hours.
The next version of this project would add a frontend integration — a simple checkout UI that calls the Payrail API — to demonstrate how the API fits into a complete payment flow rather than existing as a standalone backend.
Stack
The API backend is built with Node.js and Express, using MongoDB for storage and JWT for authentication. The documentation site runs on Docusaurus with a local search plugin and a RAG-powered AI assistant backed by Python, Flask, OpenAI, and Pinecone. The API is deployed on Render, the docs on GitHub Pages, and everything is version-controlled on GitHub.