​
Lerian APIs

This section answers frequently asked questions about Lerian’s APIs, covering general behavior, configuration, and best practices across all services..
Yes. By default, the maximum number of records per page is 100. This limit ensures consistent performance and helps manage the volume of data transferred in each request. However, you can increase this value by setting the MAX_PAGINATION_LIMIT environment variable in your deployment configuration. Once updated and the application is restarted, the API will accept larger page sizes.Important: Increasing the page size may affect response times, especially in environments handling large datasets. Always test thoroughly in staging before applying changes in production.

​
Midaz

Here, you will find the answers to common questions about Organizations, Ledgers, Accounts, Transactions, and more in Midaz.

​
Organizations

No, each Organization operates independently and does not communicate with others.
No, each license is tied to a specific Organization. If you need support for multiple Organizations, you must acquire separate licenses for each. The same rule applies to Plugins.
Yes, an Organization can have more than one Plugin associated with it.
Yes, an Organization can manage multiple Ledgers.
While you can create a Parent Organization and a Child Organization, each Organization maintains its own Ledger, operating independently. Since transactions cannot move value directly between ledgers, you need to orchestrate the transfer with the following steps:
1

Initiate a transaction in the source ledger, transferring the amount from the original account (source) to the asset’s external account (distribute). This removes the value from the original ledger.
2

Create a second transaction in the destination ledger, where the source is now the asset’s external account, and the amount is allocated to the receiving account (distribute).
This approach ensures seamless and controlled value transfers between ledgers across different organizations.

​
Ledgers

No, Ledgers do not communicate directly. Transfers between Ledgers require orchestration.
You must orchestrate the process and transfer the amount to an External Account. Typically, this involves two steps:
1

Ledger A -> External Account.
2

External Account -> Ledger B.
No, a single Ledger can support multiple Plugins. For example, a Ledger can handle both Exchange and Pix Plugins simultaneously.

​
Assets

No, each Asset is linked to a single Account. However, each Asset will also be linked to an External Account that is automatically created when the Asset is created.
Midaz is built for flexibility, supporting a wide range of Assets:
  • currency: Traditional fiat currencies like BRL, USD, and EUR.
  • crypto: Digital assets such as BTC, ETH, and other cryptocurrencies.
  • commodities: Tangible goods like gold, soybean, and oil.
  • others: Custom Assets, including loyalty points and tokenized securities.

​
Portfolios

A Portfolio groups accounts that belong to the same entity (CPF/CNPJ). For example, if a single CPF has two different segment_id values, it will also have two corresponding account_id values. To simplify retrieval, a Portfolio is created for that CPF, linking both accounts under a single structure. This ensures easier access and management of related accounts.

​
Accounts

No, each Account is associated with a single Asset, and this association cannot be changed.
An External Account is used to receive funds from outside the Ledger, effectively bringing money into the system.
Midaz automatically sets up an External Account when you create an Asset, ensuring seamless backing for all transactions flowing in and out of the Ledger.
No. Each account (account_id) can be linked to only one Segment (segment_id).
Nope. You can create as many Accounts as your setup needs. No limits, no constraints—just the flexibility to scale your way.
To understand the balance top-up process, let’s consider the following points:
  1. In the Midaz Ledger, when an Asset (e.g., BRL) is created, an External Account associated with that asset is also generated.
  2. This External Account acts as a gateway between the Lerian ecosystem and the external world. In other words, it serves as a mirror of the balances held by the institution in its PI account, settlement account, reserve account, or even a traditional bank or payment account holding the actual funds.
  3. To deposit funds into a user account with a specific Asset coming from outside the Midaz Ledger, the process is as follows:
    • Initiate a transaction where the source is the External Account and the destination is the target account(s).
    • As a result, the External Account will be debited by the transferred amount (becoming negative), while the destination account(s) will be credited accordingly, based on the values provided in the transaction payload.

​
Transactions

A Transaction must have at least two Operations. For example, transferring R$ 100 from Account A to Account B consists of:
  • Operation 1: Debit R$ 100 from Account A.
  • Operation 2: Credit R$ 100 to Account B.
Lerian provides clients with multiple options to access transaction receipts:
  1. Via APIs – Retrieve transaction data through our APIs, enabling you to generate a visual receipt in the format of your choice.
  2. Using the Reporter – Extract transaction data and create customized visual receipts.
  3. Through the Console – Access transaction information directly from the Lerian Console.

​
Entities

Currently, the Entity (entity_id) is open for external IDs, with no validation enforced by Midaz. This means you can use the IDs that already exist in your database, seamlessly integrating them into your system.

​
Idempotency

Midaz treats the request as new every time. This means retries may result in duplicated operations.
No. Keys should be scoped to a single operation and endpoint.
Only the TTL from the first request is used. Changing it later has no effect.
Yes. Midaz replays the full response, including headers and body, for completed requests.
The default window is 300 seconds (5 minutes), but you can customize it up to your allowed limit per endpoint.

​
Accounting in Midaz

A: Midaz allows you to mirror your organization’s official Chart of Accounts directly in the platform by configuring two core features:
  • Account Types – Create the logical categories from your chart (e.g., Assets, Liabilities, Revenue, Expenses) and assign them to accounts in your ledger. When the Account Types feature is enabled, the type field in the Accounts API becomes mandatory and must match one of the values you’ve registered.
  • Transaction Routing – Use Operation Routes to validate each “leg” of a transaction (e.g., debit must come from an account type user_wallet) and Transaction Routes to define complete transaction patterns that align with your accounting logic.
By combining Account Types and Transaction Routing, you can enforce your accounting rules at the ledger level — ensuring every transaction is validated and categorized according to your Chart of Accounts, without hardcoding rules in your business logic.

​
Plugins

Plugins extend the capabilities of the Midaz ledger, enabling seamless integration and process orchestration. Designed to remove complexity, they provide powerful abstractions that let you focus on your business model while ensuring efficiency and scalability. Explore the most common questions about how plugins work, their deployment, and the options available to enhance your operations.
Plugins are technologies integrated into the Midaz ledger, designed to simplify process integration and orchestration. They provide abstractions that allow clients to focus on their business model without needing to build or manage essential system logic that falls outside their domain.
No. Plugins are designed to operate exclusively with Midaz. They provide specific abstractions and orchestrate transactions based on the ledger’s structure, ensuring precise and efficient integration.
Once contracted, plugins are provided and installed within the client’s infrastructure (on-premise model), alongside their Midaz instance. Applications connect according to the specific functionality of each plugin.
Lerian provides two types of plugins, categorized by their origin:
  • Native Plugins: Developed and fully integrated into the Midaz ledger by Lerian, these plugins ensure complete support and seamless integration with the platform.
  • Marketplace Plugins: Created by Lerian’s partners to serve specific market niches, these plugins are available in the marketplace. Lerian facilitates their integration into Midaz, but their offering and support are managed directly by the respective partners.