Saldo, extrato e limites

Consulte o saldo, concilie pelo extrato e veja os limites, as tarifas e as métricas da conta.

GETConsultar saldo/transactions/balance GETConsultar extrato/transactions/statement GETConsultar limites e tarifas/transactions/limits GETConsultar métricas/transactions/metrics

As quatro rotas usam o escopo STATEMENT_READ.

Saldo

GET /transactions/balance

{
  "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.

O valor do saque mais a tarifa (withdraw em 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

GET /transactions/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).

{
  "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

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.

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

GET /transactions/limits devolve os limites e as tarifas que valem para a conta agora. Valores em centavos; feePercentage é percentual (150 = 1,5%).

{
  "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

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.