Build an account statement

Turn Midaz account operations into a clear customer statement by filtering by date, direction, and route with the List Operations by Account endpoint.

This guide explains how to transform Midaz account operations into end-user account statements.

You build an account statement from Midaz account operations. Each operation is a ledger movement that links 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. Then transform each operation into a row that users 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 that the endpoint returns.

   Required for statement queries

   Parameter	Description
   start_date	Start date of the statement period
   end_date	End date of the statement period
   limit	Number of items per page
   sort_order=desc	Returns the most recent operations first

   You need these fields for this statement use case. They define the statement window and make the result predictable for users.

   Required for pagination

   Parameter	Description
   cursor	Cursor returned from the previous response

   Optional filters

   Parameter	Description
   direction=credit	Returns only incoming operations
   direction=debit	Returns only outgoing operations
   type	Filters by operation type
   route_id	Filters by the operation route ID (UUID)
   route_code	Filters by the operation route code

   The endpoint can return the following operation types:

   Type	What it means
   CREDIT	Value entering the account
   DEBIT	Value leaving the account
   ON_HOLD	Amount temporarily locked
   RELEASE	Previously locked amount released
   OVERDRAFT	Movement related to overdraft usage
   BLOCK	System-generated account-block companion row
   UNBLOCK	System-generated account-unblock companion row

   Use type to classify the accounting movement. Use direction to decide whether the statement shows the amount as positive or negative.

   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 in the items array can become one statement row.

   Required for statement rendering

   Statement field	Operation field
   Date	createdAt
   Description	description
   Movement type	type
   Direction	direction
   Amount	amount.value
   Currency or asset	assetCode
   Balance after operation	balanceAfter.available
   Receipt or transaction reference	transactionId

   You need these fields to render a useful statement row. The API does not require all of them. A statement without them loses meaning, traceability, or balance context.

   Recommended for user-friendly statements

   Statement context	Operation field
   Counterparty	metadata.counterparty
   Document	metadata.document
   Pix key	metadata.pixKey
   End-to-end ID	metadata.endToEndId
   Channel	metadata.channel
   Category	metadata.category

   Midaz returns the ledger movement. The integrating system should add business context in the metadata of each relevant source.from[] and distribute.to[] entry when it creates the transaction; metadata does not propagate from source entries to destination entries.

   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": "[e-mail]",
       "category": "Transfer"
     }
   }
   
4. Apply statement display rules

   Use direction to determine the sign

   Direction	Display behavior
   credit	Display as a positive amount
   debit	Display 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

   Do not display operations with the following types 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

   Define a settled-operation policy

   Do not use balanceAffected as a settled-operation predicate. A normal ON_HOLD operation can set balanceAffected to true without changing the available balance. Define your statement policy explicitly from operation type and status, and show ON_HOLD and RELEASE according to the hold/release rules above.

5. Handle pagination

   The endpoint splits responses into pages according to the limit value.

   To retrieve all operations:

   1. Read the next_cursor field from the response
   2. Send it as the cursor parameter in the next request
   3. Repeat until the response no longer returns next_cursor

   Example flow:

   Request 1
     -> returns items + next_cursor
   
   Request 2
     -> cursor=next_cursor
     -> returns more items + next_cursor
   
   Repeat until next_cursor is no longer returned
   

Example statement output

After you apply filters, transform operations, and apply display rules, the final statement can look like this:

Date	Description	Amount	Balance after
2026-05-18	Pix received from John Doe	+150.00 BRL	1,240.55 BRL
2026-05-18	Card purchase	-45.90 BRL	1,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 each operation’s metadata when you create the transaction. Midaz stores those fields with that operation. The statement can use them later to show who, what, and why behind the movement.

• counterparty
• document
• pixKey
• endToEndId
• channel
• category

Example metadata:

"send": {
  "source": {
    "from": [{
      "accountAlias": "customer_123",
      "metadata": {
        "counterparty": "John Doe",
        "document": "12345678900",
        "pixKey": "[e-mail]",
        "endToEndId": "E1234567890123456789012345678901",
        "channel": "PIX",
        "category": "Transfer"
      }
    }]
  }
}

This lets you 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, the statement still works. It can then only display the accounting data that the operation returns.

Midaz keeps the ledger consistent and auditable. The integrating system adds business context to each operation’s metadata.