# Saldo, extrato e limites (/docs/conta-digital/statement) As quatro rotas usam o escopo `STATEMENT_READ`. ## Saldo [#saldo] [`GET /transactions/balance`](/docs/conta-digital/endpoints/account/get_balance) ```json { "total": 152030, "available": 150530, "blocked": 1500, "blockedBySecurity": 1500, "blockedByWithdraw": 0, "blockedByRefund": 0, "syncedAt": "2026-10-06T18:20:11.004Z" } ``` | Campo | Descrição | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `available` | O saldo disponível: o que pode ser usado agora em saque, pagamento de Pix copia e cola e estorno. É a soma das linhas do extrato. | | `blocked` | Está na conta, mas não pode ser usado, como o valor de uma contestação MED aberta ou de um saque, estorno ou transferência ainda sendo processados. `blockedBySecurity`, `blockedByWithdraw` e `blockedByRefund` separam esse valor por motivo. | `total` é `available + blocked`. Todos os campos em [Consultar saldo](/docs/conta-digital/endpoints/account/get_balance). O valor do saque mais a tarifa (`withdraw` em [limites](#limites)) precisa caber em `available`. Mesmo assim, o saque pode ser recusado com `WITHDRAW_INSUFFICIENT_PROVIDER_BALANCE`: o banco não cobre o saque naquele momento. ## Extrato [#extrato] [`GET /transactions/statement`](/docs/conta-digital/endpoints/account/get_statement)?limit=20\&dateFrom=2026-10-01\&trigger=PAYOUT Cada linha é um lançamento que mexeu no saldo disponível, não uma operação inteira. Uma cobrança paga de R$ 15,00 com tarifa de R$ 1,05 entra como `+1395`. Um saque sai na hora do pedido, com o valor e a tarifa juntos (`amount + serviceFee`). ```json { "data": [ { "id": "cmu9r1a2b000101s6stmt0002", "entryId": "cmu9r0z9y000001s6entr0002", "amount": -10250, "balanceAfter": 150530, "trigger": "PAYOUT", "description": "Reserva de saque", "originId": "cmu3wd7k1000201s6wdrw0001", "infractionProtocol": null, "gross": 10000, "fee": 250, "status": "SETTLED", "statusDetail": null, "statusReason": null, "statusAt": "2026-10-05T14:40:14.120Z", "payoutOperation": "WITHDRAW", "counterparty": { "name": null, "document": null, "pixKey": "f***@exemplo.com" }, "postedAt": "2026-10-05T14:40:11.002Z" } ], "nextCursor": "cmu9r1a2b000101s6stmt0002", "balance": 150530 } ``` | `trigger` | A linha | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | `PAYMENT` | Cobrança paga, já sem a tarifa. | | `DEPOSIT` | Pix recebido sem cobrança, já sem a tarifa. | | `PAYMENT_REFUND` | Estorno: a saída do valor, ou a volta dele quando o estorno é recusado. Também o estorno que o banco faz por conta própria. | | `PAYOUT` | Saída de saque ou de pagamento de Pix copia e cola, na hora do pedido. | | `PAYOUT_REVERSAL` | O valor do saque voltando, quando ele falhou. | | `PAYOUT_REFUND_RECEIVED` | Devolução de um Pix enviado pela conta. | | `INFRACTION_BLOCK` | Contestação MED aberta: o valor sai do saldo disponível. | | `INFRACTION_SETTLED` | Contestação procedente: o valor voltou ao pagador. | | `INFRACTION_RELEASED` | Contestação improcedente: o valor volta, menos a taxa de análise. Se a contestação foi cancelada, volta inteiro. | | `INTERNAL_TRANSFER` | Transferência entre contas, nas duas pontas. O sinal de `amount` diz o lado. | * `status` é o estado atual da operação, em saque, estorno e transferência: `PROCESSING` (ainda sendo processada), `SETTLED` (concluída) ou `RETURNED` (recusada, com o valor de volta). Nas outras linhas, vem `null`. `description` não muda depois de gravada: a saída de um saque concluído continua "Reserva de saque". * `statusDetail` vem em dois casos. `APPROVAL_REFUSED`: o banco não aprovou o saque, o valor continua fora do saldo disponível e `statusReason` traz uma mensagem para exibir. `PROVIDER_REFUND`: o banco devolveu ao pagador sem pedido seu. * `counterparty` é com quem foi a operação. Nas entradas, quem pagou: numa cobrança, o cliente que você informou, com o documento inteiro; num Pix sem cobrança, com o documento mascarado. Nas saídas, `pixKey` traz a chave de destino mascarada. Nas linhas de contestação, vem `null`. * `balance`, ao lado de `data`, é o saldo disponível agora. ### Filtros [#filtros] | Filtro | Descrição | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `originId` | O id da operação como vem nos webhooks: `paymentId`, `withdrawId`, `depositId` ou `transferId`. O `id` devolvido na criação da cobrança, do saque ou da transferência não serve aqui. | | `trigger` | Um ou mais tipos de linha, separados por vírgula. | | `dateFrom`, `dateTo` | Data sem hora vale o dia inteiro no horário de Brasília. | | `status` | Estado da operação de origem. Veja abaixo. | Os filtros valem juntos. Parâmetro que a rota não conhece é recusado com `400` e `REQUEST_UNKNOWN_QUERY_PARAM`. Todos os filtros em [Consultar extrato](/docs/conta-digital/endpoints/account/get_statement). O filtro `status` olha o estado da operação que gerou a linha, não o campo `status` da linha. Ele traz todas as linhas das operações nesse estado, inclusive as de estorno. Linhas de transferência e de contestação ficam de fora. ## Limites [#limites] [`GET /transactions/limits`](/docs/conta-digital/endpoints/account/get_limits) devolve os limites e as tarifas que valem para a conta agora. Valores em centavos; `feePercentage` é percentual (`150` = 1,5%). ```json { "payment": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 105, "feePercentage": 0 }, "withdraw": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 150 }, "externalPayment": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 }, "refund": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 }, "internalTransfer": { "enabled": true, "ticketMin": 100, "ticketMax": 1000000, "feeFixed": 100, "feePercentage": 0 }, "dailyWithdraw": { "limit": 1000000, "used": 12850 }, "dailyInternalTransfer": { "limit": null, "used": 0 }, "infraction": { "feeFixed": 500, "feePercentage": 0, "blocksBalance": true } } ``` | Bloco | Descreve | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `payment` | Cobrança. | | `withdraw` | Saque para chave. O mínimo e o máximo valem para toda saída por Pix. | | `externalPayment` | Pagamento de Pix copia e cola: os limites do saque, com tarifa própria. | | `refund` | Estorno e devolução de depósito, com tarifa própria. O máximo por operação é o do saque; o mínimo não é aplicado. | | `internalTransfer` | Transferência entre contas. | | `dailyWithdraw` | Teto diário das saídas por Pix e quanto já foi usado hoje. | | `dailyInternalTransfer` | O mesmo, para transferências entre contas. | | `infraction` | Taxa de análise cobrada quando a contestação MED é improcedente, e se o valor contestado sai do saldo disponível enquanto a análise corre (`blocksBalance`). | Em cada operação, `enabled` diz se ela está liberada, `ticketMin` e `ticketMax` são o menor e o maior valor, e a tarifa soma uma parte fixa (`feeFixed`) e uma percentual (`feePercentage`). Nos tetos diários, `limit: null` é sem teto e `0` bloqueia tudo. Com teto, `used` conta o dia no horário de Brasília, inclusive as que ainda estão sendo processadas; sem teto, vem `0`. ## Métricas [#métricas] `GET /transactions/metrics?dateFrom=2026-09-01&dateTo=2026-09-30` Sem `dateFrom` e `dateTo`, o período é dos últimos 30 dias. * As cobranças contam pela data de criação: a conversão de setembro é a parte das cobranças criadas em setembro que foi paga, mesmo que o pagamento tenha vindo em outubro. * `rails` traz um item por meio de pagamento da conta. Meio sem métricas vem com `available: false` e sem números; o Pix sem cobranças no período vem com os números zerados. * As proporções (`conversionRate`, `refundRate`, `disputeRate`) seguem o formato de `feePercentage` e vêm `null` quando não há base. * `withdrawals` soma os saques que não falharam, com a tarifa. `deposits` soma os Pix recebidos sem cobrança. `pixInflow` soma cobranças pagas e depósitos. Todos os campos estão em [Consultar métricas](/docs/conta-digital/endpoints/account/get_metrics).