A Transaction in Midaz represents a complete financial event, often involving multiple accounts. At the heart of Midaz is a powerful double-entry accounting system that ensures every financial movement is precise, reliable, and balanced.

Double-Entry Accounting

The double-entry system operates on a simple yet transformative principle: for every transaction, there are two corresponding entries—a debit and a credit. This framework ensures that all financial activities are recorded holistically, providing a complete and balanced view of your accounts.

Each transaction impacts two accounts, maintaining equilibrium in the financial ecosystem:

Debits reflect the value received or resources consumed.
Credits indicate the value given or resources provided.

For organizations leveraging Midaz’s advanced transaction capabilities, the double-entry system seamlessly integrates with our architecture. Our platform ensures that every debit and credit is automatically tracked and balanced, streamlining your financial processes.

Example

Consider this example (figure 1): you perform a transaction to transfer R$1000 from one account to another. This process will have two operations:

one operation to debit R$ 1,000.00 from the source account.
one operation to credit R$ 1,000.00 to the destination account.

The image shows a simple flowchart representing a financial transaction of transferring BRL 1,000.00. It is enclosed in a rectangle labeled "Transfer Transaction BRL 1,000.00" and contains two operations: a red "Debit Operation" box on the left with the text "@source_account - BRL 1,000.00," and a green "Credit Operation" box on the right with the text "@destination_account + BRL 1,000.00." An arrow points from the debit operation to the credit operation, indicating the flow of the transaction. — Figure 1. Example of the Operations in a transaction to transfer BRL 1.000,00.

In Midaz, these entries are automatically captured, ensuring precision and alignment with your financial strategy. Our platform’s intuitive design enables you to view and analyze these movements effortlessly, promoting a culture of financial autonomy.

N:N Transactions (Many-to-Many)

Unlike traditional financial systems that limit transactions to one-to-one or one-to-many relationships, Midaz enables N:N transactions, allowing multiple source and destination accounts within a single transaction.

Consider a marketplace payout where multiple sellers (several source accounts) are paid from a single escrow account, and each seller might also pay a fee to the platform. This could be modeled as one transaction involving many parties on both sides. Midaz can handle such a scenario in one atomic transaction, crediting and debiting all relevant accounts.

Another example is a peer-to-peer payment with fees: one transaction can debit the payer’s account and credit both the payee’s account and a fee account in one go. This capability simplifies financial flows that would otherwise require multiple steps.

Atomicity and Integrity

Transactions are atomic operations – either all constituent operations succeed, or none do. This ensures that partial financial events do not occur. If any part of a transaction fails validation (say, insufficient funds in one account), the entire transaction will not be applied, preserving ledger integrity.

Transaction Source

Transactions in Midaz can be made either from a single source or multiple sources.

🚧
Important
The sum of the values in the source must always equal the value specified right after the send and equal the sum of the values in the distribute.

Single Source

In a single source transaction, the specified amount is taken directly from one source account.

Example

In this example (figure 1):

BRL 30.00 is taken from account 1.
100% of it is sent to destinationAccount1.

Figure 1. Single source transaction. — Figure 1. Example of a single source transaction.

Code Examples

(transaction v1
  (chart-of-accounts-group-name PAG_CONTAS_CODE_1)  
  (description "single source transaction")  
  (send BRL 3000|2
    (source
      (from @account1 :amount BRL 3000|2)		
    )
    (distribute
      (to @destinationAccount1 :share 100)
    )	
  )
)

{
   "chartOfAccountsGroupName":"PAG_CONTAS_CODE_1",
   "description":"single source transaction",
   "send":{
      "asset":"BRL",
      "value":3000,
      "scale":2,
      "source":{
         "from":[
            {
               "account":"@account1",
               "amount":{
                  "asset":"BRL",
                  "value":3000,
                  "scale":2
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "account":"@destinationAccount1",
               "share":{
                  "percentage":100
               }
            }
         ]
      }
   }
}

Multi-Source

In a multi-source transaction, the amount or proportion is taken from different accounts. The total amount withdrawn from each account must be equal to the transferred amount to avoid any errors.

Example

In this example (figure 2):

BRL 30.00 will be sent to the destination account (destinationAccount1).
- BRL 15.00 will be taken from one account (account1).
- BRL 15.00 will be taken from another account (account2).
The destination account will receive 100% of the amount sent.

Figure 2. Multi-source transaction. — Figure 2. Example of a multi-source transaction.

Code Examples

(transaction v1
  (chart-of-accounts-group-name PAG_CONTAS_CODE_1)
  (description "multi-source transaction")
  (send BRL 3000|2 
    (source
      (from @account1 :amount BRL 1500|2)
      (from @account2 :amount BRL 1500|2)
    )
    (distribute
      (to @destinationAccount1 :share 100)
    )
  )
)

{
   "chart-of-accounts-group-name":"PAG_CONTAS_CODE_1",
   "description":"multi-source transaction",
   "send":{
      "asset":"BRL",
      "value":3000,
      "scale":2,
      "source":{
         "from":[
            {
               "account":"@account1",
               "amount":{
                  "asset":"BRL",
                  "value":"1500",
                  "scale":"2"
               }
            },
            {
               "account":"@account2",
               "amount":{
                  "asset":"BRL",
                  "value":"1500",
                  "scale":"2"
               }
            }
         ]
      },
      "distribute":[
         {
            "account":"@destinationAccount1",
            "share":{
               "percentage":100
            }
         }
      ]
   }
}

Transaction Destination

Similar to origins, destinations can be single or multiple.

Single Destination

In a single destination transaction, the amount is sent to only one destination account.

Example

In this example (figure 3):

BRL 30.00 is taken from an external account.
100% is sent to the destination account (destinationAccount1).

Figure 3. Example of a single destination transaction.

Code Examples

(transaction v1
  (chart-of-accounts-group-name PAG_CONTAS_CODE_1)  
  (description "single destination transaction")  
  (send BRL 3000|2
    (source
      (from @external/BRL :amount BRL 3000|2)		
    )
    (distribute
      (to @destinationAccount1 :share 100)
    )	
  )
)

{
   "chartOfAccountsGroupName":"PAG_CONTAS_CODE_1",
   "description":"single destination transaction",
   "send":{
      "asset":"BRL",
      "value":3000,
      "scale":2,
      "source":{
         "from":[
            {
               "account":"@external/BRL",
               "amount":{
                  "asset":"BRL",
                  "value":3000,
                  "scale":2
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "account":"@destinationAccount1",
               "share":{
                  "percentage":100
               }
            }
         ]
      }
   }
}

Multi-Destination

In multi-destination transactions, the transaction amount is divided among multiple destination accounts. Values can be distributed by shares, fixed amounts, or remaining balance.

Example

In this example (figure 4):

BRL 100 is taken from the source account (@account1)
38% of the amount goes to destination account 1 (destinationAccount1).
50% goes to destination account 2 (destinationAccount2).
A fixed BRL 2.00 goes to destination account 3 (destinationAccount3).
The remaining amount goes to destination account 4 (destinationAccount4).

Figure 4. Example of a multi-destination transaction.

Code Example

(transaction v1
  (chart-of-accounts-group-name PAG_CONTAS_CODE_1)  
  (description "multi-destination transaction")  
  (send BRL 3000|2
    (source
      (from @external/BRL :amount BRL 3000|2)		
    )
    (distribute
      (to @destinationAccount1 :share 38)  
      (to @destinationAccount2 :share 50)  
      (to @destinationAccount3 :amount BRL 200|2)  
      (to @destinationAccount4 :remaining)  
    )	
  )
)

{
   "chartOfAccountsGroupName":"PAG_CONTAS_CODE_1",
   "description":"multi-destination transaction",
   "send":{
      "asset":"BRL",
      "value":3000,
      "scale":2,
      "source":{
         "from":[
            {
               "account":"@external/BRL",
               "amount":{
                  "asset":"BRL",
                  "value":3000,
                  "scale":2
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "account":"@destinationaccount1",
               "share":{
                  "percentage":38
               }
            },
            {
               "account":"@destinationaccount2",
               "share":{
                  "percentage":50
               }
            },
            {
               "account":"@detinationaccount3",
               "amount":{
                  "asset":"BRL",
                  "value":"200",
                  "scale":"2"
               }
            },
            {
               "account":"@destinationaccount4",
               "remaining":"remaining"
            }
         ]
      }
   }
}

Multi-Source and Multi-Destination

These complex transactions involve multiple sources and multiple destinations. This is useful for scenarios like a crowdfunding campaign where contributions are pooled and distributed among multiple recipients.

Example

In this example (figure 5):

BRL 4,000.00 will be donated and the amount will be taken from four different accounts.
- 25 % will be taken from account 1 (@account1).
- 25 % will be taken from account 2 (@account2).
- 40 % will be taken from account 3 (@account3)
- 10 % will be taken from account 4 (@account4)
The donations will be sent to four donation accounts and each will receive an equal 25% share of the total.

Figure 5. Example of a multi-source and multi-destination transaction.

Code examples

(transaction v1  
  (chart-of-accounts-group-name PAG_CONTAS_CODE_1)  
  (description "multi-source and multi-destination transaction")  
  (send BRL 400000|2  
    (source  
      (from @account1 :share 25)		  
      (from @account2 :share 25)  
      (from @account3 :share 40)  
      (from @account4 :share 10)  
    )
    (distribute  
      (to @donation1 :share 25)  
      (to @donation2 :share 25)  
      (to @donation3 :share 25)  
      (to @donation4 :share 25)  
    )
  )
)

{
   "chartOfAccountsGroupName":"PAG_CONTAS_CODE_1",
   "description":"multi-source and multi-destination transaction",
   "send":{
      "asset":"BRL",
      "value":"400000",
      "scale":"2",
      "source":{
         "from":[
            {
               "account":"@account1",
               "share":{
                  "percentage":25
               }
            },
            {
               "account":"@account2",
               "share":{
                  "percentage":25
               }
            },
            {
               "account":"@account3",
               "share":{
                  "percentage":40
               }
            },
            {
               "account":"@account4",
               "share":{
                  "percentage":10
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "account":"@donation1",
               "share":{
                  "percentage":25
               }
            },
            {
               "account":"@donation2",
               "share":{
                  "percentage":25
               }
            },
            {
               "account":"@donation3",
               "share":{
                  "percentage":25
               }
            },
            {
               "account":"@donation4",
               "share":{
                  "percentage":25
               }
            }
         ]
      }
   }
}

Transaction Flow

When a transaction is initiated, two conditions are verified:

the source account has a sufficient balance of the specified asset
the statuses of both source and destination accounts permit sending and receiving transactions (allowSending, allowReceiving).

If these conditions are met, the specified amount is transferred from the available balance of the source account to the destination account. This process is synchronous, and upon success, the transaction status will be APPROVED. Consequently, users should initiate the transaction only if they intend to commit it to the ledger.

Inflows and Outflows

Midaz uses a double-entry ledger system where all external account interactions (inflows and outflows) are handled through the external account of the Asset (@external/{{assetCode}} ), which represents the link between Midaz and external transactions.

Example Scenario: A PIX transfer from Account A (which is part of the Ledger) to an external BRL account.

Source: @accountA
Destination: @external/BRL account

The Ledger entries for this transaction are:

Source	Destination	Amount
@accountA	@external/BRL	BRL 1000
@external/BRL	@accountB (Bank B)	BRL 1000

Here, BRL 1000 is moved from Bank A’s account to @external/BRL for the outflow. Once the transfer is processed via SPI (PIX system), Bank B credits the funds to the recipient’s account.

📘
Notes

@external/{{assetCode}} can have a zero or negative balance but should never be positive.

This account's balance will always equal the negative of the combined balance of all ledger accounts.

Initiating a Transaction

There are two main ways to initiate a transaction:

Using DSL

A Domain-Specific Language (DSL) simplifies user interaction by focusing on specific domain concepts, enabling non-developers to perform complex tasks without technical skills. DSLs reduce boilerplate code and embed constraints in their syntax, enforcing business rules and minimizing errors. However, their predefined patterns can limit flexibility, making it harder to create custom parsers or adapt to new requirements.

The Transactions DSL in Midaz, called Gold, simplifies transaction processing with an intuitive accounting syntax. It stores transaction information in .gold files, allowing business teams to define transactions easily and fostering collaboration between technical and business workflows.

To use the DSL, follow these steps:

Create the .gold file according to the Transactions DSL structure.
Submit the file using the Create a Transaction using DSL endpoint.

📘
Learn More
For more information about the structure of the DSL, refer to the Transactions DSL page.

Using JSON endpoint

JSON endpoints provide a flexible and developer-friendly standard for data interchange, enabling precise control over request structures tailored for custom workflows and specific use cases. Their broad compatibility with various programming languages makes integration and debugging easier.

However, this flexibility can result in verbosity and user errors, as developers are required to handle validation manually. For non-developers, the complexity of JSON may present challenges, making it less intuitive than a Domain-Specific Language (DSL) for everyday tasks.

To create a transaction using JSON, use the Create a Transaction using JSON endpoint.

Managing Transactions

To further manage your Transactions, you can use the Transactions API.

View Transactions Details

To view the details of all Transactions, use the List Transactions endpoint.
To view the details of a specific Transaction, use the Retrieve a Transaction endpoint.

Edit a Transaction

To edit Transaction details, use the Update a Transaction endpoint.

Transactions

Double-Entry Accounting

Example

N:N Transactions (Many-to-Many)

Atomicity and Integrity

Transaction Source

🚧
Important

Single Source

Example

Multi-Source

Example

Transaction Destination

Single Destination

Example

Multi-Destination

Example

Multi-Source and Multi-Destination

Example

Code examples

Transaction Flow

Inflows and Outflows

📘
Notes

Initiating a Transaction

Using DSL

📘
Learn More

Using JSON endpoint

Managing Transactions

View Transactions Details

Edit a Transaction

Double-Entry Accounting

Example

N:N Transactions (Many-to-Many)

Atomicity and Integrity

Transaction Source

🚧Important

Single Source

Example

Multi-Source

Example

Transaction Destination

Single Destination

Example

Multi-Destination

Example

Multi-Source and Multi-Destination

Example

Code examples

Transaction Flow

Inflows and Outflows

📘Notes

Initiating a Transaction

Using DSL

📘Learn More

Using JSON endpoint

Managing Transactions

View Transactions Details

Edit a Transaction

🚧
Important

📘
Notes

📘
Learn More