How Stripe Prevents Double Payment Using Idempotent API

#45: A Simple Introduction to Idempotent API (4 minutes)

Get the powerful template to approach system design for FREE on newsletter sign-up:

---

This post outlines how Stripe implements idempotent API. If you want to learn more, scroll to the bottom and find the references.

• Share this post & I'll send you some rewards for the referrals.

Note: This post is based on my research and may differ from real-world implementation.

2010 - California, United States.

Two brothers want to run a business.

Yet they found it difficult to set up an online payment for it.

So they pivoted to create an online payment service and called it Stripe.

Double Payment Problem

As number of users grew, double payment became an issue for them.

That means, mistakenly charging a user twice for the same transaction.

Here are some reasons for this:

1. Server Error

The request fails while the server processes it.

The Transaction Fails During Processing

But the client doesn’t know whether the request was successful or not.

So it isn’t safe to retry.

Otherwise, there might be a double payment.

2. Network Error

The server processed the request successfully.

But the network connection failed before returning a response to the client.

The Connection Fails Before Returning a Response to the Client

So the client doesn’t know if the request was successful.

Hence it isn’t safe to retry.

Otherwise, there might be a double payment.

Hungry Minds (Featured)

Learning system design is about staying hungry.

Hungry Minds scans 100+ sources for the best deep dives, trends, and tools for software engineers to stay ahead.

Join 9,001+ engineers from big tech to startups for 1 free digest every Monday.

---

Idempotent API

They wanted to solve the double payment problem in the best possible way.

And as in most cases, the simplest solution is the best solution.

So they created an idempotent API.

It guarantees that a specific request can be retried many times without side effects.

That means a specific request gets processed exactly once even after many retries.

Here’s how Stripe implements idempotent API:

1. Idempotency Keys

They should process a request only if it wasn't processed earlier.

This means they must track requests processed by the server.

So they create a unique string (UUID) to use as the idempotency key.

And send it with each request’s HTTP header.

Also they generate a new UUID whenever the request payload changes.

Imagine the idempotency key as a fingerprint to find whether a request has already been processed.

Using Idempotency Key to Prevent Double Payment

They store the idempotency keys with an in-memory database on the server side.

And cache the server response after a request gets processed successfully.

So the in-memory database gets queried to check whether a request has been processed.

They process a request only if it's new and then store its idempotency key in the database.

Otherwise, the cached response gets returned. This means the request was processed earlier.

Also they roll back a transaction using the ACID database when a server error occurs.

Besides they remove the idempotency keys from the in-memory database after 24 hours.

It helps to reduce storage costs and gives enough time to retry failed requests.

Put another way, an idempotency key could be reused after that period.

2. Retrying Failed Requests

Although it’s safe to retry using an idempotency key, there’s a risk of server overload with many requests.

Exponential Backoff With Jitter While Retrying Requests for Reliability

So they use the exponential backoff algorithm.

That means the client adds an extra delay to retry after each failed request.

Besides a failed server could experience a thundering herd problem when many clients try to reconnect at once.

So they use jitter to add randomness to the client’s waiting time before a retry.

Idempotency is essential to reliable online payments.

Also it offers better security and user experience.

While Stripe remains one of the biggest online payment services in the world.

---

👋 PS - Are you unhappy at your current job?

And preparing for system design interviews to get your dream job can be stressful.

Don't worry, I'm working on content to help you pass the system design interview. I'll make it easier - you spend only a few minutes each week to go from 0 to 1. Yet paid subscription fees will be higher than current pledge fees.

So pledge now to get access at a lower price.

"Excellent system design golden nuggets to ace technical interviews. Highly recommend." Irina

---

Consider subscribing to get simplified case studies delivered straight to your inbox:

---

Follow me on LinkedIn | Twitter | Instagram

---

Thank you for supporting this newsletter. Consider sharing this post with your friends and get rewards. Y’all are the best.

---

How McDonald’s Food Delivery Platform Handles 20,000 Orders per Second

How Dropbox Scaled to 100 Thousand Users in a Year After Launch

---

References

• Designing robust and predictable APIs with idempotency

• Idempotent requests at Stripe

• Advanced error handling at Stripe

• Idempotency and retries with Stripe

• What Is an Idempotent API?

• Making retries safe with idempotent APIs

• Using Idempotency Keys

• Idempotency at PayPal

• API idempotency at Adyen