Implementing Idempotence in a Payments Microservice



2857 views Backend System Design



Idempotence is executing the same action multiple times, but the result is as if the operation was applied just once.

Example: Double tapping a post multiple times on Instagram does not increase the like count. It just increases the first time and by 1.

Idempotence becomes extremely critical when money is involved. If A wants to transfer money to B, the transfer should happen just once. If due for any reason, the payment is implicitly retried, the funds will be deducted twice, which is unacceptable.

Why would a transaction repeat?

Before we talk about idempotence, it is important to understand why it would repeat in the first place.

Consider a situation where the payments service initiated a payment with a Payment Gateway, the money got deducted, but the payments service did not get the response. This would make the Payments service retry the API call, which would lead to a double deduction.

Implementing idempotence

Check and Update: Weave everything with a single ID.

The idea is to retry only after checking if the payment is processed or not. But how do we do this? The implementation is pretty simple- a global payment ID that weaves all the services and parties together.

The flow is:

  1. Payments service calls the PG and generates a unique Payment ID
  2. Payments service passes this ID to the end-user and all involved services
  3. Payments service initiates the payment with Payment Gateway with this ID specifying the transfer between A and B
  4. If there are any failures, the Payment service retries and in that request specifies the Payment ID
  5. Using the payment ID, the payment gateway checks if the transfer was indeed done or not and would transfer only when it was not done

Although we talked about the Payments service here, this approach of implementing idempotence is pretty common across all the use cases. The core idea is to have a single ID (acting as the Idempotence Key) weaving all the involved services and parties together.


Arpit Bhayani

Arpit's Newsletter

CS newsletter for the curious engineers

❤️ by 17000+ readers

If you like what you read subscribe you can always subscribe to my newsletter and get the post delivered straight to your inbox. I write essays on various engineering topics and share it through my weekly newsletter.




Other essays that you might like


An in-depth introduction to Rolling Deployments

944 views 46 likes 2022-05-27

One of the simplest deployment strategies that make deployment a breeze is Rolling Deployment. It is the most widely ado...

Implementing Vertical Sharding

1124 views 75 likes 2022-05-25

Sharding is super-important when you want to handle the traffic that cannot be handled through one server. Sharding come...

An in-depth introduction to Blue Green Deployments

1309 views 60 likes 2022-05-18

Deployments are a pain if we are unsure about our release changes. But sometimes even if we know our changes well, somet...

An in-depth introduction to Canary Deployments

1982 views 117 likes 2022-05-16

Deployments are stressful; what if something goes wrong? What if you forgot to handle an edge case that was also missed ...


Be a better engineer

A set of courses designed to make you a better engineer and excel at your career; no-fluff, pure engineering.


System Design Masterclass

A masterclass that helps you become great at designing scalable, fault-tolerant, and highly available systems.

Enrolled by 700+ learners

Details →

Designing Microservices

A free course to help you understand Microservices and their high-level patterns in depth.

Enrolled by 17+ learners

Details →

GitHub Outage Dissections

A free course to help you learn core engineering from outages that happened at GitHub.

Enrolled by 67+ learners

Details →

Hash Table Internals

A free course to help you learn core engineering from outages that happened at GitHub.

Enrolled by 25+ learners

Details →

BitTorrent Internals

A free course to help you understand the algorithms and strategies that power P2P networks and BitTorrent.

Enrolled by 42+ learners

Details →

Topics I talk about

Being a passionate engineer, I love to talk about a wide range of topics, but these are my personal favourites.




Arpit's Newsletter read by 17000+ engineers

🔥 Thrice a week, in your inbox, an essay about system design, distributed systems, microservices, programming languages internals, or a deep dive on some super-clever algorithm, or just a few tips on building highly scalable distributed systems.



  • v12.4.4
  • © Arpit Bhayani, 2022

Powered by this tech stack.