A key aspect of Midaz's operational integrity is its commitment to avoiding duplicate transactions and ensuring the uniqueness of entities such as Accounts and Ledgers. Through carefully designed strategies, Midaz provides a secure and reliable environment for transaction processing and entity management.

This guide aims to explain how Midaz maintains transaction uniqueness and preserves database integrity, equipping users with a comprehensive understanding of its approach to idempotency and duplication.

Transactions

Midaz employs idempotency keys to ensure transactions are processed only once. Users are encouraged to use these keys to prevent duplicate transaction processing.

Generating an Idempotency Key

The idempotency key must be generated by the client. We recommend creating an MD5 hash from the following elements to ensure uniqueness:

• Transaction amount
• Source
• Destination
• Asset code

Using the Idempotency Key

When making a POST request to /v1/transactions, include the generated idempotency key in the idempotencyKey query parameter. Midaz then stores this key in the cache, along with the request timestamp and status, formatted as hash:timestamp:status_request.

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

Cache and Tolerance Window

The idempotency key cache is refreshed every 24 hours, conserving system resources.

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 window in seconds.

For instance, if a user submits a new transaction after the initial 60 seconds, the system will process it, provided it meets the necessary criteria. This flexibility balances protection against duplicate transactions with user control over transaction timing.

Preventing Entity Duplication

To prevent duplicating other entities, such as Accounts and Ledgers, Midaz enforces unique naming for each entity. If an entity name already exists in the database, the creation process is halted, and a notification is sent to the user about the duplication.

This approach ensures that each entity within the Midaz ecosystem has a unique identifier, enhancing data integrity and preventing confusion. By enforcing uniqueness at the point of creation or registration, Midaz streamlines data management and prevents redundancy.