Transactions

Use the Transactions domain to handle the entire lifecycle of transactions, from the creation of transaction types to movements and accounting flows.

Transaction Creation

To create a transaction using our API, the user must send a specific payload to the transaction creation endpoint with the octet-stream type, containing the Transaction DSL, or use a Transaction Template.

To create a transaction, use the Create a Transaction endpoint.
To list all transactions of an account, use the Retrieve all transactions endpoint.
To retrieve a specific transaction, use the Retrieve a transaction by id endpoint.

Transaction Updates

Since Midaz is an immutable ledger, only part of the transaction data can be edited.

To perform these updates, use the Update a transaction endpoint.

Operation update

If you update the operations, the transaction will not be updated.

Transaction Validation

When you create a transaction, a series of checks are triggered by the system to ensure smooth execution.

Idempotency Key Check: The system first verifies if the provided idempotency key (if included) allows the transaction, based on the tolerance parameter value in the header.
Balance Check: The system ensures that the balances of the source and destination accounts are equal.
Account Permissions: The system confirms that the source accounts have the accounts.allowSending parameter set to true, and the destination accounts have the accounts.allowReceiving parameter set to true.
Instrument Conversion: If multiple instruments are specified in the statement, the system checks the conversion rates in the instrument_rates table.
Sufficient Balance: Finally, the system validates that the source accounts have enough balance to complete the transaction.

If all validations are positive, and the user does not specify the pending parameter (used for pre-transactions), the system will move the balances from the available balance (balance.available) of the source accounts to the destination accounts.

Balance and Movements

For the transaction to proceed, the sum of balances in the source accounts must equal the sum of balances in distribute. If this is true, the balance will be moved from the balance.available of the source account to the destination account.

Transactions and operations are stored in their respective tables (transactions and operations), always saving the value and the scale used. However, the balance in the accounts table will always be returned using the smallest possible scale.

Pre-Transaction

For enhanced security, users can start a pre-transaction process where funds are transferred from the originating account's available balance to an on-hold status, marked as "PRE_APPROVED."

This functionality is beneficial for several reasons:

Recording Unapproved Transactions: Users may want to register all transactions in Midaz, even those that haven't been approved yet. In this scenario, they initiate a pre-transaction to reserve the balance and then conduct a series of validations on their side. These validations can include AML (Anti-Money Laundering) checks, limit checks, and other compliance measures.
Daily Transaction Review: Users can review transactions at the end of the day, looking for those with a status of "CREATED" (similar to a transitory account-model). If such transactions are found, it indicates that one of the flows failed and the transaction did not reach a final status (either "SENT" or "DECLINED").

By setting the pending parameter in the transaction statement, the value is transferred from the source account's available balance to its on-hold balance, rather than directly to the target account's available balance.

To create a pre-transaction, use the Create a Pre-Transaction endpoint.

This feature is invaluable for users who want comprehensive ledger documentation, including transactions subject to external validation and potential rejection.

Additionally, the pre-transaction mechanism helps identify potential discrepancies in daily transaction flows. Transactions marked as "PRE_APPROVED" at the end of the day may indicate underlying issues that need attention.

Committing or Canceling Pre-Transactions

Once a pre-transaction is created, users have two options: commit the transaction (for final approval) or cancel it.

Committing a Pre-Transaction

To commit the pre-transaction, use the Confirm a Pre-Transaction endpoint.

If all conditions for successful transaction completion are met, the status is updated to "APPROVED," formalizing the transaction in the ledger. When initiating transactions, ensure your intent to commit the transaction to the ledger is clear to avoid unnecessary complications.

Canceling a Pre-Transaction

If the user wants to cancel a pre-transaction, they must create a reversal transaction. This changes the status from "PRE-APPROVED" to "CANCELED," and the amount on hold is returned to the originating account.

Reversal Transaction

In the Transactions domain, an important feature is the ability to reverse transactions when needed. Since Midaz works on an immutable ledger, a transaction cannot be canceled once it is made.

However, you can use the Revert a transaction endpoint to initiate a reversal process by executing the original transaction statement but with the source and destination reversed.

As a result, the reversed transaction will inherit an ID parameter that is identical to the originating transaction's ID (parentTransactionId). Ultimately, both transactions will conclude with an "APPROVED" status.

The specific business rule for each transaction must be adhered to.

The indiscriminate use of "revert" can lead to accounting issues. For instance, when reversing a TED due to incorrect bank details, the paid fee would also be refunded, which may not be desired.

Transaction exchange rates

To enable a user to debit an amount in one currency and send it in a different currency during a transaction, it is important to store the exchange rate for the currency pair in Midaz.

We recommend using the Exchange Satellite service for reliable updates. However, if the service is not used, the manipulation of these exchange rates can be done using the following endpoints of the Instrument rates API:

To create an exchange rate, use the Create an instrument rate endpoint.
To retrieve all exchange rates, use the Retrieve all instrument rates endpoint.
To retrieve a specific exchange rate, use the Retrieve an instrument rate by id endpoint.
To update an exchange rate, use the Update an instrument rate endpoint.
To remove an exchange rate, use the Delete an instrument rate endpoint.

For the most accurate and up-to-date quotes, we recommend using the Exchange Satellite service. This ensures that currency pairs are updated robustly and reliably, minimizing the need for manual quote manipulation.

Managing Operations

Similar to transactions, Operations can be manipulated partially. To ensure compliance with the double-entry principle, operations cannot be created in isolation. Since the sum of the operation amounts equals the transaction value, operations cannot be removed either.

The possible operations are:

Listing: Primarily used to create an extract.
Editing: Used for adjusting descriptions, metadata, and other editable fields.

List of Operations

The list of operations closely resembles a statement for two main reasons:

Operations are the most granular aspect of the ledger, directly impacting the balance.
Given that a transaction can involve multiple accounts (n:n), more than one account can be involved.

Using the Retrieve all Transactions endpoint to create statements is not recommended, as it may expose one user’s balance to another when multiple operations are involved.

There are two main ways of listing operations:

By Account: Recommended for listing transactions on the same instrument, as each account is tied to a single instrument.
By Portfolio: Useful for extracting multiple transactions, such as in a Global account, where users may want to list transfers made in different currencies (e.g., BRL, CHF, USD). It’s also used for operations involving exchanges (e.g., purchasing different shares).

You can use the following endpoints to manage Operations:

To list the Account Operations, use the Retrieve all Operations endpoint.
To list a specific Operation by Account, use the Retrieve an Operation by id endpoint.
To list the Portfolio Operations, use the Retrieve all Portfolio Operations endpoint.
To list a specific Portfolio Operation, use the Retrieve a Portfolio Operation by id endpoint.
To update an Operation, use the Update an Operation endpoint.

Transaction charts

In the Midaz Console, you can view charts that provide an overview of important Ledger metrics. There are three main types of graphs:

Total Transactions: Compiles the SENT transactions in the database for the specified ledger.
Transactions by Status: The total transactions categorized by their status.
Top Instruments: The total amount allocated in accounts to the ledger instruments.

For scalability, all endpoints used to generate charts will accept startDate and endDate parameters and will use the same route, only changing the type specified in the request body.

To create a transaction chart, use the Request a Chart endpoint. This endpoint is used to create Total Transactions and Transactions by Status charts.
- To create Total Transactions charts, use "type": "totalTransactions".
- To create Transactions by Status charts, use "type": "transactionsByStatus".
- To create the Top Instruments charts, use "type": "totalAmountByInstrument".

Refer to the Charts API page for more information.

PreviousAccounts API NextDomain-Specific Language (DSL)

Last updated 2 days ago