Idempotency

---

This documentation page delves into the sophisticated mechanisms employed by Midaz to address the challenges of idempotency and entity duplication. Central to Midaz’s operational integrity is its commitment to preventing duplicate transactions and ensuring the uniqueness of entities within its ecosystem, such as Accounts and Ledgers. Through a series of meticulously engineered strategies, Midaz tackles these issues head-on, offering a secure and reliable environment for transaction processing and entity management. This guide aims to elucidate the methods by which Midaz maintains transaction uniqueness and preserves database integrity against entity duplicity. It is designed to equip users with a comprehensive understanding of Midaz’s approach to idempotency and duplication, fostering confidence in the platform’s ability to safeguard data and transactions with the highest level of precision and care.

Transactions

To ensure transactions are not processed multiple times, Midaz implements the use of idempotency keys. It’s highly recommended that users utilize these keys to prevent duplicative transaction processing.

Generating an Idempotency Key

The idempotency key must be generated by the client. We recommend using an MD5 hash comprising the following elements:

• Transaction amount

• Source

• Destination

• Instrument code

This in turn ensures uniqueness and prevents duplicate transactions.

Using the Idempotency Key

When making a POST request to /v1/transactions, include the generated idempotency key in the query parameter idempotencyKey. Upon receiving this key, Midaz stores it in cache alongside the timestamp of the request and its status, formatting the cache entry as hash:timestamp:status_request.

If a new request with the same hash (and therefore, the same transaction details) is received within 60 seconds of a successful request, Midaz will not process the transaction and will return a 409 error to avoid duplication.

Cache and Tolerance Window

The cache of idempotency keys is reset every 24 hours, freeing computational resources and ensuring system efficiency.

To adjust the idempotence window from the default 60 seconds, users can include a tolerance query parameter in their POST request to /v1/transactions, specifying the desired duration in seconds.

For example, if after the initial 60 seconds a user attempts a new transaction, the system will process it successfully if it meets the criteria outlined.

This mechanism ensures a balance between protecting against duplicate transactions and allowing users flexibility in transaction processing.

Other entities

Midaz employs a direct method to prevent the duplication of other entities such as Accounts, Ledgers, etc, by enforcing uniqueness in entity names, for example. When users attempt to create or register entities with names that have already been used, the system automatically checks for name redundancy within its database. If a duplicate name is detected, the creation process is halted, and the user is notified of the duplication issue. This ensures that each entity, whether it be an Account, Ledger, or any other component within the Midaz ecosystem, maintains a unique identifier in terms of its name. The prevention of duplicity directly upon the creation or registration call streamlines the data integrity process, making the system more efficient and reducing the likelihood of user confusion or data mishandling.