Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt

Use this file to discover all available pages before exploring further.

This guide explains how integrators can transform Midaz account operations into end-user account statements. An account statement in Midaz is built from account operations. Each operation is a ledger movement linked to an account, such as a credit, debit, hold, release, or overdraft event. To build a statement, retrieve the account operations for the period, keep the operations that affect the statement view, and transform each operation into a row that users can understand.
Account balance flow
1

Retrieve account operations

Use the List Operations by Account endpoint to list operations for a specific account:
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/operations
2

Apply query filters

Use query parameters to define the statement period, control pagination, and filter the operations returned by the endpoint.

​
Required for statement queries

ParameterDescription
start_dateStart date of the statement period
end_dateEnd date of the statement period
limitNumber of items per page
sort_order=descReturns the most recent operations first
These fields are required for this statement use case. They define the statement window and make the result predictable for users.

​
Required when paginating

ParameterDescription
cursorCursor returned from the previous response

​
Optional filters

ParameterDescription
direction=creditReturns only incoming operations
direction=debitReturns only outgoing operations
typeFilters by operation type
Supported operation types:
TypeWhat it means
CREDITValue entering the account
DEBITValue leaving the account
ON_HOLDAmount temporarily locked
RELEASEPreviously locked amount released
OVERDRAFTMovement related to overdraft usage
Use type to classify the accounting movement. Use direction to decide whether the amount is shown as positive or negative in the statement.Example request:
GET /v1/organizations/org_123/ledgers/ledger_001/accounts/account_456/operations?start_date=2026-05-01&end_date=2026-05-31&limit=50&sort_order=desc
3

Transform operations into statement entries

Each object returned in the items array can become one statement row.

​
Required for statement rendering

Statement fieldOperation field
DatecreatedAt
Descriptiondescription
Movement typetype
Directiondirection
Amountamount.value
Currency or assetassetCode
Balance after operationbalanceAfter.available
Receipt or transaction referencetransactionId
These fields are required to render a useful statement row. They are not all required by the API, but a statement without them loses meaning, traceability, or balance context.
Statement contextOperation field
Counterpartymetadata.counterparty
Documentmetadata.document
Pix keymetadata.pixKey
End-to-end IDmetadata.endToEndId
Channelmetadata.channel
Categorymetadata.category
Midaz returns the ledger movement. The integrating system should add business context in metadata when the transaction is created.Example transformation:
{
  "date": "2026-05-18T14:23:11Z",
  "description": "Pix transfer received",
  "type": "CREDIT",
  "direction": "credit",
  "amount": "150.00",
  "asset": "BRL",
  "balanceAfter": "1240.55",
  "transactionId": "txn_987654",
  "metadata": {
    "counterparty": "John Doe",
    "pixKey": "john@example.com",
    "category": "Transfer"
  }
}
4

Apply statement display rules

​
Use direction to determine the sign

DirectionDisplay behavior
creditDisplay as a positive amount
debitDisplay as a negative amount
Do not use type to determine whether the value is positive or negative. The type field classifies the accounting movement, while direction defines whether the value enters or leaves the account.

​
Handle hold and release operations separately

Operations with the following types should not be displayed as regular settled movements:
  • ON_HOLD
  • RELEASE
Instead:
  • ON_HOLD should appear as a balance hold or temporary lock
  • RELEASE should appear as a balance release or unlock

​
Display only settled operations

For a settled statement view, include only operations where:
"balanceAffected": true
This keeps the statement focused on movements that changed the available balance.
5

Handle pagination

Responses can be paginated depending on the selected limit.To retrieve all operations:
  1. Read the next_cursor field from the response
  2. Send it in the next request using the cursor parameter
  3. Repeat until next_cursor is no longer returned
Example flow:
Request 1
  -> returns items + next_cursor

Request 2
  -> cursor=next_cursor
  -> returns more items + next_cursor

Repeat until next_cursor is null

​
Example statement output

After applying filters, transforming operations, and applying display rules, the final statement can look like this:
DateDescriptionAmountBalance after
2026-05-18Pix received from John Doe+150.00 BRL1,240.55 BRL
2026-05-18Card purchase-45.90 BRL1,194.65 BRL
The API does not return a ready-made statement page. It returns ledger events that the integrating system turns into a statement experience.

​
Add business context

The operations endpoint returns accounting events. A user-facing statement needs more context than the ledger movement alone. Send business metadata in the transaction payload when creating the transaction. Midaz stores those fields with the operation, and the statement can use them later to show who, what, and why behind the movement.
  • counterparty
  • document
  • pixKey
  • endToEndId
  • channel
  • category
Example metadata: 
"metadata": {
  "counterparty": "John Doe",
  "document": "12345678900",
  "pixKey": "john@example.com",
  "endToEndId": "E1234567890123456789012345678901",
  "channel": "Pix",
  "category": "Transfer"
}
This makes it possible to display entries such as:
  • “Pix received from John Doe”
  • “Card purchase at Coffee Shop”
  • “Transfer to Savings Account”
instead of generic accounting descriptions. If the integrating system does not send these fields when creating the transaction, the statement still works, but it can only display the accounting data returned by the operation.
Midaz keeps the ledger consistent and auditable. Business context belongs in transaction metadata, added by the integrating system.