Idempotency

In MBanq's API ecosystem, idempotency plays a crucial role in ensuring the consistency and integrity of financial operations. This concept guarantees that making the same API request multiple times produces the same result as if it were only executed once. Idempotency prevents unintended duplicate actions and provides developers with a reliable mechanism for maintaining data integrity in financial transactions.

Idempotency is achieved through the use of an idempotent key, a unique identifier associated with a specific API request. The purpose of the idempotent key is to prevent duplicate requests from being processed more than once.

Why is Idempotency Important?

Consider a scenario where a FinTech sends an API request to initiate an ACH payment. Due to factors like network issues or latency, the response from the API service may be delayed or lost. In such cases, the FinTech might not receive a response indicating the status of the payment initiation.

Without an idempotent key, the FinTech might assume that the initial request was not processed and attempt to resend the same request. However, this can lead to potential issues such as double payments or incorrect transaction amounts if the original request was indeed processed successfully.

How Idempotency Works

By including the idempotent key in the API request, the FinTech can ensure that even if they resend the same request multiple times, the API service will recognize the idempotent key and identify it as a duplicate request. The service will then check its records to see if the payment request with that specific idempotent key has already been processed. If it has, the service will return a response indicating that the payment has already been successfully processed, preventing any duplication or inconsistencies.

Implementing Idempotency in MBanq Cloud API's

📘

API Endpoint Reference in this tutorial:

• ACH Transfers
• Transfers

Let's take a look at an example of using the idempotent key in an API request for creating a transfer in the MBanq Cloud API.

POST /v1/transfers?command=create HTTP/1.1
Host: api.cloud.mbanq.com
Content-Type: application/json
x-idempotency-key: 12345689

{
  "type": "CREDIT",
  "paymentType": "INTERNAL",
  "amount": "122",
  "debtor": {
    "identifier": "id:5",
    "accountType": "SAVINGS"
  },
  "creditor": {
    "identifier": "id:3",
    "name": "Rakesh Ranjan Behera",
    "accountType": "SAVINGS"
  },
  "reference": [
    "internal tran"
  ]
}

In this example, we include the idempotent key x-idempotency-key with the value "12345689" in the header of the API request. This unique identifier allows the Mbanq Cloud API service to recognize duplicate requests.

Upon successful processing of the request, the API service will return a response that includes the resource ID of the new transfer:

{
  "clientId": 2,
  "savingsId": 5,
  "resourceId": 17,
  "resourceIdentifier": "1677572588398mP"
}

Concluding Thoughts

The Importance of Storing Idempotent Key:

The Idempotency key is stored at our end for 60 minutes. During this period, if the same key is used in subsequent API requests, the system recognizes it as a duplicate and prevents the redundant execution of the request.

By leveraging idempotency in MBanq's APIs, developers can design robust applications that gracefully handle retries, failures, and network issues without compromising data integrity or introducing inconsistencies into financial operations.