Idempotent API: How Stripe Ensures Reliable Payments

Hello there fellow coders and web surfers! While making online payments, we’ve all experienced a case where the amount was deducted from our bank account, but the page shows an error. Then, we retry the payment, only to end up with a double charge.

This is a frustrating situation, but what if there was a way to prevent it? Enter Idempotent APIs — the unsung heroes behind reliable payment systems like Stripe, ensuring that even if a payment request is retried, you won’t end up paying twice.

In 2010, in California, USA, two brothers wanted to run a business but ran into problems with receiving payments online. So, they decided to create their own online payment service called Stripe. Fast forward to today, and Stripe is now the largest online payments provider out there.

As users kept increasing and using their services, double spending become an issue to them. This is when users where charged twice for the same transaction. Here are some reasons for this:

1. Server Error

• The server was unable to process the payment.

• The client doesn’t know if the payment was successful or not.

Retrying the payment isn’t safe, as it could lead to a double spend.

2. Network Error

• A client-side network error occurs during the payment process.

• The client doesn’t know if the payment was successful or not.

• Retrying the payment isn’t safe, as it could result in a double spend.

Idempotent Apis

They wanted to solve the double payment problem in the best way possible. And as with most things in life, the simplest solution is usually the best one.

So, they came up with idempotent APIs.

These APIs guarantee that a specific request can be retried as many times as needed without any side effects. In simple terms, it means the same request gets processed exactly once, no matter how many retries happen.

Here’s how Stripe does it:

• Idempotency keys are used to avoid double payments.

• When a client makes a request, it generates a unique ID (AGJ6FJMkGQIpHUTX) and sends it with the request.

• The server receives the ID and matches it to the request state.

• If the client retries the request with the same ID:
  - For a connection failure, the server processes the request as if it’s the first time.
  - For a failure midway, the server picks up where it left off (if the previous operation was safely rolled back).
  - For a response failure, the server sends back the cached successful result.

• Stripe uses Idempotency-Key header on POST requests to ensure safe retries, preventing duplicate operations.

curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -H "Idempotency-Key: AGJ6FJMkGQIpHUTX" \
   -d amount=2000 \
   -d currency=usd \
   -d description="Charge for Brandur" \
   -d customer=cus_A8Z5MHwQS7jUmZ

• Idempotency keys make retries safe, but too many retries can overload the server.

• To avoid this, Stripe uses the exponential backoff algorithm.
  - This means the client adds a delay that increases after each failed request.

• Jitter is added to the delay to introduce randomness.
  - This prevents a “thundering herd” problem, where too many clients try to reconnect at once.

Do checkout the offical docs at https://stripe.com/blog/idempotency

Conclusion

Making sure your API is idempotent can really take your payment system to the next level. In this post, we went over how Idempotency keys help avoid double payments and keep things smooth when retries are needed. We also looked at how Stripe tackles potential server overloads with exponential backoff and jitter. With these techniques, you can keep your operations safe, reliable, and stress-free for both customers and businesses.