Idempotency Key

Idempotency Key

One important concept I learned while working in fintech is Idempotency Key. It's a fundamental aspect of fintech products that I wasn't familiar with before entering the industry. An idempotency key is a unique identifier attached to API calls to ensure that when issue happens in the API calls, such as duplicate API calls, the operation related to that identifier won't repeat their mutating actions. To put it simply, idempotency means that performing the same operation multiple times should produce the same result as executing it once.

This concept is critical in fintech because the software primarily deals with moving money between systems. Double deductions are serious mistakes that developers must avoid or immediately fix if they happens. Working with money requires extreme caution due to the significant consequences of errors, losing customer money requires the company to return the money.

Practical Example: Wallet Deduction API

Let's examine a common fintech operation, deducting balance from a user's wallet. The initial API specification might look like this:

POST /wallet/8a3b1e42-1855-47de-a628-25fdbff01258/spend
{
    "amount": 5.89,
    "currency": "USD",
    "remarks": "Coffee at Starbucks"
}

In distributed systems, where applications consist of multiple microservices, various issues can arise. Your API consumers might experience problems that lead to unintentional duplicate calls. This creates concerns for both the API consumers and their customers, who obviously don't want to be charged twice for a single purchase.

Implementing Idempotency

To solve this, you can add an idempotency_key to your API. Usually it is in the form of an UUID. This can be implemented either in the JSON body or as a header:

// Option 1: In JSON body
POST /wallet/8a3b1e42-1855-47de-a628-25fdbff01258/spend
{
    "idempotency_key": "b0a4bd28-f9e9-4dec-b7f0-ec5ae6a0edba",
    "amount": 5.89,
    "currency": "USD",
    "remarks": "Coffee at Starbucks"
}

// Option 2: In header
POST /wallet/8a3b1e42-1855-47de-a628-25fdbff01258/spend
Idempotency-Key: b0a4bd28-f9e9-4dec-b7f0-ec5ae6a0edba
{
    "amount": 5.89,
    "currency": "USD",
    "remarks": "Coffee at Starbucks"
}

The API response should include the idempotency key:

HTTP Status 200 OK
{
    "id": "transaction_5a693df0-e3ae-491c-8b3e-3fce301127de",
    "idempotency_key": "b0a4bd28-f9e9-4dec-b7f0-ec5ae6a0edba",
    "balance": "94.11",
    "status": "processing"
}

If the API is called again with the same idempotency key, it should return a duplicate error:

HTTP Status 400
{
    "error": "duplicated_transaction"
}

Retrieving Transaction Status

You can also provide an endpoint to query transaction status using the idempotency key:

GET /wallet/8a3b1e42-1855-47de-a628-25fdbff01258/spend?idempotency_key=b0a4bd28-f9e9-4dec-b7f0-ec5ae6a0edba

Response:
{
    "id": "transaction_5a693df0-e3ae-491c-8b3e-3fce301127de",
    "idempotency_key": "b0a4bd28-f9e9-4dec-b7f0-ec5ae6a0edba",
    "balance": "94.11",
    "status": "processing"
}

With these implementations, your API is now idempotent.