Transactions
A transaction is the fundamental entity of the Ledger.
It represents the transfer of funds from one account (source) to another (destination), but not only one to another. You can also have many-to-many configurations.
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. 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. Example of a multi-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 1500|2)
(from @account2 :amount BRL 1500|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":"account 1",
"amount":{
"asset":"BRL",
"value":"1500",
"scale":"2"
}
},
{
"account":"account2",
"amount":{
"asset":"BRL",
"value":"1500",
"scale":"2"
}
}
]
}
},
"distribute":{
"to":[
{
"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 @destinationAccount :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":"destinationAccount",
"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 10000|2
(source
(from @account1 :share 100)
)
)
(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":"10000",
"scale":"2",
"source":{
"from":[
{
"account":"@account1",
"share":{
"percentage":100
}
}
]
}
},
"distribute":{
"to":[
{
"account":"@account2",
"share":{
"percentage":38
}
},
{
"account":"@account3",
"share":{
"percentage":50
}
},
{
"account":"@account4",
"amount":{
"asset":"BRL",
"value":"200",
"scale":"2"
}
},
{
"account":"@account5",
"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.
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
.goldfile 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.
Pre-transactions
Alternatively, users may initiate a pre-transaction to hold the specified amount before the final commitment. In this scenario, the balance is taken from the balance available of the source account and is temporarily put on hold, the transaction status is set to PRE_APPROVED.
This approach is useful when users want to record all transactions, even those potentially subject to later disapproval due to external validation.
- To create a pre-transaction, set the
pendingfield totruewhile creating the transaction.
After creating a pre-transaction, you must either commit it or revert it.
- To commit the pre-transaction and finalize it, use the Commit a Pre-Transaction endpoint.
- If the pre-transaction is committed, and all criteria are still met (i.e., both accounts are eligible for participation, the status of the transaction is updated to APPROVED.
- To revert the pre-transaction, use the Revert a Transaction endpoint.
- If a pre-transaction is reverted, its status will change from PRE_APPROVED to CANCELED. The balance that was previously on hold will be returned to the available balance of the source account, and a new transaction entry will be created to log this adjustment.
Transactions reversal
Transactions can also be reversed if deemed necessary, though this does not cancel the original transaction, as Midaz operates with an immutable ledger. Instead, a reversal duplicates the original transaction’s steps but swaps the source and destination accounts. Users can create a reversal transaction with the parentTransactionId set to the original transaction ID. Both the original and reversal transactions will have a final status of APPROVED.
- To revert a transaction, use the Revert a Transaction endpoint.
Warning
Reversals should adhere strictly to the transaction’s business rules. Using reversals indiscriminately may lead to accounting issues. For instance, if a bank transfer (TED) incurs a fee of R$2, reverting the transaction due to an incorrect recipient would also return the fee, which might not align with expected use cases.
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.
Updated 15 days ago