Financial information

Use the balance to check how much the account holds at the time of the request and what portion is available. The values can change with new receipts, withdrawals, refunds, holds, and releases.

Charge statistics show totals by period. They help you track receipts. The forecast estimates what may still be received during the period. Neither replaces a balance request.

Retrieve the current balance

Use Retrieve the balance, with GET /v1/balances. The response shows amounts in Brazilian real cents.

The request does not reserve money. A withdrawal or refund remains subject to its own conditions, limits, and another balance check when requested.

Understand the values

If the account has R$ 100.00 in total and R$ 30.00 blocked, the response is:

{
  "total_amount_cents": 10000,
  "blocked_amount_cents": 3000,
  "available_amount_cents": 7000
}

A hold preserves the total amount and reduces the available balance. Releasing it makes the amount available again; it does not represent a new receipt. The total retains any negative value, while the available balance is zero when there is no amount free to use.

Balance and statement

The balance shows current amounts. The Statement shows recorded financial entries, with their types and references. Adding up a page or filtered entries does not replace a balance request.

The balance response does not show how much the account held after a past entry. To check a transaction, use Retrieve an entry.

Charge statistics

Use Retrieve charge statistics, with GET /v1/charges/statistics, to track counts, amounts, and payment rate in an ERP, report, or your own dashboard. The request gathers totals for the key's company and environment, so you do not need to traverse every page of charges.

The issued, issued_paid, and received groups provide count for the quantity and amount_cents for the amount in Brazilian real cents. Amounts are gross, without deducting fees or refunds. A refunded charge remains in these totals at its original amount while it is in one of the included states. Disputed charges are not included in issued_paid or received. The request does not show the account's available balance.

For example, a charge created yesterday and paid today is included in received in today's request. It is not included in today's issued or issued_paid, because it was created outside that period.

To check individual charges, use List charges. To find how much money is available in the account, use Retrieve the balance.

Statistics period and updates

If the response reports INVALID_FIELDS with period and INVALID_VALUE in error.details, choose one of the accepted periods. Send period only once. Custom dates in start_at or end_at are not filters: an unknown parameter receives UNKNOWN_QUERY_PARAMETER.

The period parameter accepts today, last_7_days, last_15_days, and last_30_days. When omitted, the request uses today. Periods use calendar days in São Paulo time and include the current day. last_7_days, for example, starts at midnight six days ago and ends at midnight tomorrow.

start_at and end_at are response fields, not filters. They provide the inclusive start and exclusive end of the period in Unix seconds UTC. Use these boundaries to identify the report's interval. The request accepts only the periods listed in period, without custom start and end dates.

Totals can take a few seconds to reflect a creation, payment, refund, or deletion. updated_at provides the latest update to the retrieved data, or null when this information is unavailable. Repeated requests do not bring the update forward.

Expected receipts

Use Retrieve expected receipts, with GET /v1/balances/forecast, to track the same financial estimate shown in the Dashboard Summary.

receivable_amount_cents shows confirmed payments that the calculation still includes as expected receipts within the selected period. The request does not add open charges or look for future due dates. The period refers to the expected receipt date, not the charge's creation date.

projected_balance_cents adds this estimate to the account's current total balance. For example, a total balance of R$ 100.00 with R$ 25.00 expected gives a projected R$ 125.00. The amount may include blocked balance and does not confirm bank settlement, a guaranteed deadline, or availability for withdrawal. Use Retrieve the balance to check the current total, blocked, and available amounts.

The period parameter accepts today, last_7_days, last_15_days, and last_30_days; the default is today. Periods include today and use the São Paulo calendar. last_7_days, for example, starts at midnight six days ago and ends at midnight tomorrow. This request does not project the next seven, fifteen, or thirty days.

start_at provides the inclusive start and end_at the exclusive end of the period. forecast_date identifies the estimate's reference day, at midnight today in São Paulo. These fields use Unix seconds UTC.

Values can take a few seconds to reflect changes in payments. updated_at provides the forecast data's update time, or null when it is unavailable. An estimate of zero does not prove that all payments have settled. In Sandbox, values are simulated and do not represent real receipts.

Withdrawals being processed

Use Retrieve withdrawals being processed to track the total of withdrawals still awaiting completion. The request requires a Production API key and includes withdrawals with status PENDING or PROCESSING.

processing_count provides the number of withdrawals, and processing_amount_cents adds the requested amounts, including the fee, in Brazilian real cents. When no withdrawals have these statuses, both fields return zero.

This total represents money committed to the requests. Do not add it to the available balance or treat it as a confirmed credit to the destination account. To check each request and its result, use List withdrawals. Retrieving the summary does not request another withdrawal or change the progress of existing ones.

Company and environment

These requests require an API key and use the company and environment associated with it. A Sandbox key retrieves the simulated balance, separate from the Production balance. The console accepts only Sandbox keys.

You do not need to send a company or account in the request body. Handle errors using the HTTP status and error.code, as described in HTTP response codes.