Skip to navigation

Balance, daily balance and account close

Current balance, daily balance series and closing an account, on https://tenant.api.corpx.com. Every call carries Authorization: Bearer {token} and X-Tenant-Id.

Balance

GET /v1/accounts/{accountId}/balance

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/balance" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-yourcompany"
{
"accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
"total": 18254.17,
"locked": 500.00,
"available": 17754.17,
"currency": "BRL",
"updatedAt": "2026-02-05T22:00:00Z"
}

available is what the account can send. locked is the total held (for example a MED hold); the response does not list each hold. includeLocks is accepted for compatibility and has no effect.

Daily balance

GET /v1/accounts/{accountId}/daily-balance?startDate=2026-06-04&endDate=2026-06-05

Returns, per day, the opening balance (total / blocked / available) and the day’s flows, in Brasília time. Max window 30 days; without dates, the last 30 days. Closings exist only from 2026-06-04 (cutoffDate).

{
"accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
"startDate": "2026-06-04",
"endDate": "2026-06-04",
"cutoffDate": "2026-06-04",
"timezone": "America/Sao_Paulo",
"items": [
{
"date": "2026-06-04",
"openTotalBalance": 10000.00,
"openBlockedBalance": 0,
"openAvailableBalance": 10000.00,
"pixIn": 1200.00,
"pixOut": 300.00,
"pixBillingOut": 1.50,
"tedIn": 0,
"tedOut": 0,
"tedBillingOut": 0,
"internalTransferIn": 0,
"internalTransferOut": 0,
"internalTransferBillingOut": 0,
"bankSlipOut": 0,
"stablecoinBurn": 0,
"stablecoinMint": 0,
"cardSettlementIn": 845.30,
"cardSettlementOut": 0,
"currency": "BRL"
}
],
"fetchedAt": "2026-06-05T12:00:00Z"
}

Flows are summed by type, always present, and 0 when there was no movement:

TypeInflowsOutflowsFees
PixpixInpixOutpixBillingOut
TEDtedIntedOuttedBillingOut
Internal transferinternalTransferIninternalTransferOutinternalTransferBillingOut
Boleto—bankSlipOut—
BRMTstablecoinMintstablecoinBurn—
Card settlementcardSettlementIn (debit, credit and receivables prepayment)cardSettlementOut—

A day’s opening balance is the previous day’s opening plus that day’s inflows, minus its outflows and fees.

Close the account

POST /v1/accounts/{accountId}/close

Removes your tenant’s access to the account. People need the tenant_manager or admin role; credentials need the accounts.close scope (legacy api2/write still passes). Send an Idempotency-Key so the call can be retried safely.

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/close" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-yourcompany" \
-H "Idempotency-Key: close-2e6b725b-001"
{
"accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
"message": "Este tenant perdeu o acesso à conta. Ela será encerrada em breve se nenhum outro tenant estiver usando."
}

The 200 is the same whether another CorpX tenant still operates the account or yours is the last one. The account is not deleted: it becomes status=closed. Repeating the request on an account already closed in your tenant returns the same 200, with no new closure request.

When the account is yours alone, the closure is requested from the settlement bank, which only accepts a zeroed account: no available balance and no locked balance. The settlement-bank balance is checked first:

SituationResponseWhat to do
Available balance other than zero422 account_has_balanceWithdraw the balance and retry.
Zero available, but a locked balance remains (for example a MED hold)422 account_has_locked_balanceWait for the hold to be released and retry.
Zeroed balance200The closure is requested from the settlement bank and access is removed in the same call.

In both 422 cases the account stays active and the body carries the settlement-bank balance:

{
"errorCode": "account_has_locked_balance",
"message": "para cancelar a conta no liquidante é preciso liberar o saldo bloqueado antes",
"errorReason": "para cancelar a conta no liquidante é preciso liberar o saldo bloqueado antes",
"balance": {
"total": 50.00,
"available": 0,
"locked": 50.00,
"currency": "BRL"
}
}

The bank account itself is closed when the settlement bank processes the request; the 200 does not say when.

Other errors:

StatusCodeWhen
404account_not_foundMissing account, another tenant’s account, or suspended. Never 403 tenant_mismatch.
403forbiddenA person without the tenant_manager or admin role (a viewer, for example).
403insufficient_scopeA credential without the accounts.close scope.
409request_in_progressThe same Idempotency-Key is still being processed.
503banking_unavailable / email_unavailableSettlement bank or request filing unavailable. The account stays active; try again later.