Cash visibility

Mambu Payments retrieves account statements from your partner banks. It extracts balances and transactions from each statement and links both to a connected account. Balances show where an account stands. Transactions show what moved it. Both carry the bank_data.file_id of the source statement, so you can trace them to the same file. Query both through the API to build a position, explain it, and check it.

Key concepts

Term	Definition
Connected account	A bank account that Mambu Payments reads statements from. Every balance and transaction belongs to one connected account, identified by `connected_account_id`. Learn more about connected accounts.
Balance	The amount of money held on a connected account at a given point in time. The `amount` is always positive. The `direction` sets the sign: `credit` is positive and `debit` is negative. Learn more about balances.
Transaction	A single debit or credit booked on a connected account. The `amount` is always positive, and `direction` shows whether money came in or went out. Learn more about transactions.
Booked and available	A booked balance includes only transactions booked on the account. An available balance also reflects items that the bank has not booked yet.
Booking date and value date	The `booking_date` is when the bank registers a transaction on the account. The `value_date` is when the transaction is effectively credited or debited.

Balance types

A bank sends several balances for the same day. Each type combines a status (booked or available) with a timing (opening, interim, or closing).

Type	Meaning
`opening_booked`	Booked balance at the start of the business day. Equals the previous day's `closing_booked`.
`opening_available`	Available balance at the start of the business day.
`interim_booked`	Booked balance during the business day, based on booked entries only. Can change before end of day.
`interim_available`	Available balance during the business day. Can change before end of day.
`closing_booked`	Booked balance at the close of the business day.
`closing_available`	Available balance at the close of the business day.
`previously_closed`	Closing booked balance from the previous statement.
`expected`	Projected end-of-day balance, combining booked entries with pending items.
`forward_available`	Available balance projected for a future value date.
`info`	Balance provided for information only. It is not part of the account's ledger.
`undefined`	No balance type was set or present.

The meaning of a type can differ between banks. Check with your partner banks before you rely on any type, in particular previously_closed, expected, forward_available, info, and undefined.

Get the current position

To see where every account stands, list the latest balance for each connected account and currency.

Send a GET request to /balances with latest set to true.
Read the type of each balance to know whether it is interim or closing.
Convert each amount to a signed value using direction.
Sum the signed values per currency.

The following request returns the latest balance per connected account and currency.

curl "https://sandbox.numeral.io/v1/balances?latest=true&currency=EUR" \
  -H "x-api-key: <api_key>"

The response contains one balance for each connected account.

{
  "records": [
    {
      "id": "210910eb-a84a-40f6-ac68-7a2c18d62692",
      "object": "balance",
      "connected_account_id": "ff1714ae-3ec8-450d-984c-c6ee44c82a88",
      "amount": 1200000,
      "currency": "EUR",
      "direction": "credit",
      "type": "interim_booked",
      "date": "2026-10-19",
      "bank_data": {
        "file_id": "26f4ca1c-65b0-412f-b464-206721d1e6d8",
        "statement_id": "STS-C4RR9YPLL0HHIFFHR-D8CEX3"
      },
      "created_at": "2026-10-19T09:14:32Z"
    },
    {
      "id": "7c1e3b52-9d40-4f0a-b6a8-3d52e1f0a947",
      "object": "balance",
      "connected_account_id": "3b9f6a10-5c27-4e8d-a1f4-82d7c0b5e613",
      "amount": 350000,
      "currency": "EUR",
      "direction": "debit",
      "type": "closing_booked",
      "date": "2026-10-18",
      "bank_data": {
        "file_id": "8e2d41a7-0b6c-4f93-a5d1-6c7b9e03f2a8",
        "statement_id": "STS-K7WQ2MZP81TNBXCDA-F4HJ9L"
      },
      "created_at": "2026-10-19T00:12:41Z"
    }
  ]
}

The first account holds 12,000.00 EUR and the second is overdrawn by 3,500.00 EUR. The total position is 8,500.00 EUR.

To report settled cash for a past day instead, filter on type, start_date, and end_date. Use closing_booked for settled cash and closing_available for spendable cash.

curl "https://sandbox.numeral.io/v1/balances?type=closing_booked&start_date=2026-10-12&end_date=2026-10-16" \
  -H "x-api-key: <api_key>"

Explain a balance movement

To see what moved an account on a given day, compare its balance change with its transactions.

List opening_booked for the connected account and date.
List closing_booked for the same connected account and date.
List transactions booked on that date for the same connected account.
Add the credit amounts and subtract the debit amounts.
Compare the result with the difference between the closing and opening balances.

Filter transactions on start_booking_date and end_booking_date. The start_date and end_date filters use the transaction creation date, which differs from the booking date.

curl "https://sandbox.numeral.io/v1/transactions?connected_account_id=ff1714ae-3ec8-450d-984c-c6ee44c82a88&start_booking_date=2026-10-16&end_booking_date=2026-10-16" \
  -H "x-api-key: <api_key>"

In this example, the account opens at 1,200,000 and receives two credits and one debit.

opening_booked                  1,200,000
+ credit_transfer (credit)        250,000
+ instant_credit_transfer          40,000
- direct_debit (debit)             80,000
= expected closing_booked       1,410,000

If the result differs from the actual closing_booked, check whether a statement is missing. Then compare booking_date with value_date on the transactions involved.

Note: In principle, opening booked balance plus credits minus debits equals closing booked balance. The documentation does not guarantee it. Test the relationship on your own accounts before you build controls on it.

Report cash flows by category

To see where cash comes from and goes to, group transactions by category and direction.

Send a GET request to /transactions with start_booking_date, end_booking_date, and connected_account_id.
Page through the results until you retrieve every record.
Group the records by category, direction, and currency.
Sum amount in each group.

The following request returns direct debit transactions for October 2026.

curl "https://sandbox.numeral.io/v1/transactions?category=direct_debit&start_booking_date=2026-10-01&end_booking_date=2026-10-31&limit=100" \
  -H "x-api-key: <api_key>"

The category values include credit_transfer, instant_credit_transfer, direct_debit, cheque, card, cash_pooling, account_balancing, cash_concentration, fx, and loan. The transaction object lists every value.[^3]

Limits and constraints

Item	Value
Page size	`limit` accepts 1 to 100. Default: 25.
Next page	Pass the last record's `id` as `starting_after`.
Balance sort order	By `date`, then by type. Default: `desc`.
Transaction sort order	By `created_at`. Default: `desc`.
Amount format	Integer in the currency's smallest unit. `2000` is 20.00 EUR.
Freshness	Data arrives with each bank statement. Compare `created_at` with your statement schedule.
Missing balance	A gap in the data, not a zero balance.

If your bank sends no intraday statements, you have only opening and closing balances.

Balance object