What makes Stripe's API so great?

APIs are magical. They allow to integrate any internal & external services together to create whatever you want.

However at this game, all APIs are not equal. In the payment processing industry, one stood out from its inception: Stripe. What was once a six lines of code's payment processing API now let you manage subscriptions, issue cards or verify identities.

When your product is an API, how you build & evolve your product significantly add or remove complexity for everyone relying on it.

Let's define what makes Stripe API magical:

• How Stripe engineers manage to keep improving it without impacting negatively their customers
• List takeaways you can apply to build a public API

It is built for its users, engineers

Understanding its value & how to use it

There's nothing worse than spending an hour browsing a password-protected online documentation to finally discover that what you were looking for is, in fact, not documented.

As an engineer, you're looking for this feeling of "getting it" even before starting to build something with a new tool. If integrating a new API feels like a tedious task, you will want to find alternatives.

Stripe's landing pages & online sandboxes play a key role at this. For each business area (Payment, Business operations, etc.), you can choose from integration guides, sample open source projects or no-code alternatives.

Based on your existing infrastructure, industry and needs, you already know which steps to take & the different options at your disposal.

Integrating it with your existing stack

Building something that involves finance is always intimidating. Stripe knows that & tries to make everything around it as convenient as possible.

By choosing REST, they embraced a technology which is universal and has a rich supporting ecosystem (cURL, Postman, etc.). Engineers can reuse all the knowledge they acquired on HTTP status codes, verbs for specific actions or JSON responses.

Open source clients in many programming languages are also available through Composer, NPM or Ruby Gems, embracing each development environments.

Moreover, Stripe's documentation supports many types of users:

• The ones who like to go through step-by-step tutorials with in-depth guides
• The ones who like to explore on their own with API definitions & types

Finally, Stripe's philosophy around updates is mainly centered around usage: will the experience feel consistent with existing resources, how might it break users expectations, what's the friction to adopt this new resource.

By asking these questions, you're making sure the overall API keeps its promise: it's easy to build with.

It makes Payment processing look easy

Do you know what is the difference between a payment settlement and payout processing? I don't, and to be honest, I already have enough concepts to master in my own industry to start becoming an expert in payment processing.

Exposing a domain without its complexity is no easy task. Yet, Stripe has found ways to do so using resources like PaymentIntent , PaymentMethod or Subscription .

Depending on the payment method, the country & regulations, the result of charging someone can be synchronous or asynchronous, require manual step or be directly approved. The concept of PaymentIntent abstracts all that complexity away & gives you a status property, whatever the payment method so that the overall experience feels approachable.

This also applies to Stripe's various business areas built as independent blocks like Checkout, Billing or Identity. Based on your needs, you can compose things & make your integration evolve. You can start accepting one-shot payments, move to subscriptions or even specific quotes for big clients.

It is reliable & predictable

Accepting money online might be a huge part of your business, especially if you're in ecommerce for example. When choosing an external solution, there're a few things you want from an API:

• To be reliable (it better be charging people correctly every time)
• To be predictable (once my integration is working, it better keep working as long as I need to)

API versioning is important for the later. Once deployed, you want your integration to be predictable & avoid any unintended breaking change. Stripe makes sure that your app use the same version of their API as long as it's needed. You only need to upgrade once you're ready, even if it means sticking to a 2011 release.

When working with money, predictability also comes from making sure your API is fault-tolerant and does not perform some operations twice accidentally like charging a credit card.

This concept, called idempotency, allows you in case of network connection errors for example, to retry multiple times the same operation while ensuring its result won't change. With Stripe, this concept can be leveraged with idempotency keys in POST requests. Even in case of failures, you're confident your users won't be charged twice.

The bottom line

Having & maintaining a public API is a challenge in itself. However, it can sets apart two products, allowing customers to easily interconnect their ecosystem with your solution.

In the API world, there are all sorts of things ranging from average to greatness. Stripe has found ways to provide value and a consistent technical experience over time. Let's get some inspiration from that and apply it to your next public API.

5 things to take from Stripe's API

• Express your domain without jargon
• Know your API main use cases & describe them in documentation guides
• Choose a standard like REST that feels familiar
• Use API versioning & make it explicit
• Make responses easy to use
  • Always paginate unbounded lists
  • Use nested objects for related fields instead of a flat structure
  • Represent dates consistently (Timestamp, ISO 8601)
  • Rely on enums instead of booleans for statuses (eg. charged, failed)

Sources

• Stripe's Payment APIS: the first ten years
• APIs as infrastructure: future-proofing Stripe with versioning
• How Stripe builds APIs and teams