January 13, 2024

Justin Kazmierczak

The Importance of Good Documentation: Lessons From The Stripe API.

The Importance of Good Documentation: Lessons From The Stripe API.


Published on January 13, 2024

Justin Kazmierczak

Stripe is one of the top payment gateway systems for application developers. It offers some consumer-facing products, but its bread and butter is a robust API. I recently launched a landing page for our latest product, "Pages by The Universe." Custom-designed websites built to optimize your digital presence - currently hand-crafted with plans to launch a more do-it-yourself approach as the product matures. The landing page is this sleek animated front page that takes you to an equally nifty payment collection screen. Scrolling to the bottom of that page, you'll see a Stripe "Payment Element" integrating card, bank, and buy now pay later payment methods.

It looks easy! Our testers loved the experience and said they'd feel great handing over the doe for a luxury experience comparable to what they experienced—seeing as I built that experience for that exact purpose - to help you feel both confident in the brand and secure in forking over up to $7500 for a freshly minted website. It's an integrated experience that few checkout systems have.

The problem: integrating payment gateways just plain old sucks. If you want more information on our web design packages, click the button below or scroll past for the rest of the blog entry.

Let's design your website,

Start the next quarter right with a freshly designed website created on a world-class platform and developed with a strategic design, taking your business to the next level.

A curated selection of websites designed with Pages by The Universe.

I'm not too fond of Documentation.

My first experience with documentation came from Microsoft's Developer Network (MSDN), and it was tragic. Functions needed to be appropriately documented (because they weren't), versioning was noted, and what you expected to work after reading the documentation didn't work as expected. Outside of some well-documented open-source projects, 90% - if not 99% of all documentation has this problem.

Stripe's Documentation

The excellent news is Stripe offers you custom code to help move you in the right direction, but it makes a lot of assumptions. It assumes you'll rely on its latest consumer-facing product (which historically doesn't fare well for the client), or it thinks you'll depend on it to do all the data storage and collection for you.

Why? Consumer-facing products seem more manageable to integrate, and they promote connection within Stirpe's ecosystem. It's less locked in than Shopify's ecosystem is. Corporations promote their products to you, so you'll use them more until it creates something called "Vendor Lock." Apple, Shopify, and maybe Google do this often - intentionally or unintentionally - because it guarantees you can't go anywhere. Just read any of their developer's terms yourself to learn that they don't want you to leave their ecosystem - they want you to stay on it so they can make more money from you, their customers, and their bottom line.

I don't like the lack of control, and the level of integration on Stripe's consumer products is just as tricky as the ones with API-driven solutions.

Reality Check

Ok. I hate when technology makes you go through hoops. I do. The reality is I have to give Stripe props. They've taken a seemingly tricky problem and created solutions light years ahead of old-school payment gateways.

Payment gateways usually store credit card data and tokenize it later (although tokenization is new). That's a lot of PCI compliance, error response codes, and VPNs to set up.

With Stripe, I don't need to be in PCI compliance. I give them the ability to put secure iframes on my payment page, and they collect, store, tokenize, and protect the financial information. They need to do a more decent job of providing systems to help.

My security practices come from HIPPA-compliant products developed for other clients. Even if I don't need PCI compliance, in most cases, I would be compliant. However, security is a shell game of moving parts, keeping secrets (or certificates), and balancing performance tradeoffs.

Take a Breathe

If you've completed a payment anywhere before, you are used to being redirected to multiple screens on multiple pages and praying that everything goes well. I intuitively built a single-page design that relies on fetch and other secure protocols to communicate and receive instructions from Stripe regarding payment status, next steps, and completions.

To you, it's a seamless integrated experience with beautiful animations that make you go - that was cool!

The reality is Stripe's documentation could be more complete for custom scenarios. They only offer integration suggestions or customization for integrations with consumer-facing products. They don't want you to worry about database engineering and webhook creation, BUT they have well-documented functions and procedures. They have a global one-page API document that lets me search for anything. So when I get an error, I was never told I would get - I can search their documentation and, with some problem-solving solving, work magic.

Stripe may need more brain power when it comes to documentation. They can't know or perceive everything that someone will want to do with their API. Instead, they give you the best solutions for new customers and offer more details to customers like me who build systems from scratch.

Logging and Command Line Interfaces

Now, the best thing about Stripe is not the API. However, I found their API helpful even if I ran into versioning issues and error messages that I didn't know I would. I fell in love with the logs and their Webhooks CLI.

Every action in Stripe, and for good reason, is recorded with a universal ID. I can take that ID on the associated account and see great details on the action, the response, and the status of customer orders.

The Stripe CLI allows me to route webhook requests (probably through web sockets - a key feature of future universe apps) to a private instance of a web server. So, my web server in a development environment can receive all webhooks from Stripe. This was essential when completing payments, such as with Affirm or connecting to your bank securely.

Any payment method redirecting the user to a new experience will prompt an update using a webhook. A specialized call back to your web server from its web server. It's like passing messages in class when the teacher's away. The order receives updates even when the user is no longer on your website, allowing bank deposits to be set up, payments to be completed, and emails to be sent to anyone who needs them!

What's the lesson here?

First, Open source documentation is often light years better than corporate documentation because it showcases what real users will do, not your favorite product. Documentation becomes less about marketing and more about - this is how you do this and the common problems you will encounter.

Second, when you can let your API offer complete and total logging of all processes, the biggest reason to do this is for adaption- and early adaption in cases like Pages by The Universe. I log everything during development and constantly diagnose new features and tests using this data. Now, I'm selective about the data I receive, but it's helpful to know if something somewhere has changed. For instance, during testing, I changed how my database stored the order, and Stripe never received the updated order object. My logs allowed me to watch all transactions, updates, and webhooks to find the most straightforward bug.

Logs help developers discover assumptions they made and correct the data. The data don't lie. It is what it is based on what you created it to be. Updating it is as simple as revising your code, logging those changes, watching the logs, and amending missing connections to that data that you may not be appropriately documented.

This leads back to the importance of documentation, and you need to know where things are to update them. Code isn't an evil villain waiting for you to hit compile so it can crash. It's a tool sculpted based on every comma and semicolon or crash on a lack of one.

Lastly, offering webhook CLIs (a command line interface; yes, developers still use terminal or command prompts) is the best way for a developer to test a solution from end to end. This makes production environments less restricted by bugs and free to offer users the expected experience. Of course, you should always test both environments. Sometimes, you'll find variables missing production updates because someone - who will remain nameless - hardcoded it for a test.

Lesson learned, Which is good news for future products in the pipeline from The Universe. Make the developers' lives easier so they can focus on being the creative engineers they are and less on figuring out what "param" is missing because of a flag someone set somewhere.