The System Design Newsletter

The System Design Newsletter

Share this post

The System Design Newsletter
The System Design Newsletter
How Stripe Prevents Double Payment Using Idempotent API

How Stripe Prevents Double Payment Using Idempotent API

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

Neo Kim's avatar
Neo Kim
May 09, 2024
409

Share this post

The System Design Newsletter
The System Design Newsletter
How Stripe Prevents Double Payment Using Idempotent API
30
42
Share

Get my system design playbook for FREE on newsletter signup:


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.

Idempotent API
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 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 While 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.

system design newsletter

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.

Join Hungry Minds


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 Idempotent Keys to Prevent Double Payments
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
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.

system design newsletter

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.


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


Author NK; System design case studies
Follow me on LinkedIn | YouTube | Threads | Twitter | Instagram

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

system design newsletter

Share


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

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

Neo Kim
·
May 3, 2024
Read full story
How Dropbox Scaled to 100 Thousand Users in a Year After Launch

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

Neo Kim
·
April 23, 2024
Read full story

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

Jem's avatar
Nil's avatar
Ankit Gupta's avatar
Roman Letodiani's avatar
Kujtesa's avatar
409 Likes∙
42 Restacks
409

Share this post

The System Design Newsletter
The System Design Newsletter
How Stripe Prevents Double Payment Using Idempotent API
30
42
Share

Discussion about this post

User's avatar
Akram EL Basri's avatar
Akram EL Basri
May 9, 2024

I love your work !

Expand full comment
Like (6)
Reply
Share
1 reply by Neo Kim
Fran Soto's avatar
Fran Soto
May 11, 2024

Great to see how they solved an initial problem of retries!

Still, exponential backoff + jitter could create a retry storm if there are calls multiple layers deep. So use it with care! If those multiple layers exist, implementing some retry budget with a token bucket or circuit breakers can help to avoid taking everything down on retries.

Expand full comment
Like (4)
Reply
Share
1 reply by Neo Kim
28 more comments...
8 Reasons Why WhatsApp Was Able to Support 50 Billion Messages a Day With Only 32 Engineers
#1: Learn More - Awesome WhatsApp Engineering (6 minutes)
Aug 27, 2023 â€¢ 
Neo Kim
751

Share this post

The System Design Newsletter
The System Design Newsletter
8 Reasons Why WhatsApp Was Able to Support 50 Billion Messages a Day With Only 32 Engineers
25
How PayPal Was Able to Support a Billion Transactions per Day With Only 8 Virtual Machines
#30: Learn More - Awesome PayPal Engineering (4 minutes)
Dec 26, 2023 â€¢ 
Neo Kim
270

Share this post

The System Design Newsletter
The System Design Newsletter
How PayPal Was Able to Support a Billion Transactions per Day With Only 8 Virtual Machines
14
How YouTube Was Able to Support 2.49 Billion Users With MySQL
#48: Break Into Vitess Architecture (4 minutes)
May 31, 2024 â€¢ 
Neo Kim
296

Share this post

The System Design Newsletter
The System Design Newsletter
How YouTube Was Able to Support 2.49 Billion Users With MySQL
10

Ready for more?

© 2025 Neo Kim
Publisher Privacy
Substack
Privacy ∙ Terms ∙ Collection notice
Start writingGet the app
Substack is the home for great culture

Share

Create your profile

User's avatar

Only paid subscribers can comment on this post

Already a paid subscriber? Sign in

Check your email

For your security, we need to re-authenticate you.

Click the link we sent to , or click here to sign in.

User's avatar

Petar Ivanov, a subscriber of The System Design Newsletter, shared this with you.