Saldos e caixa livre

Para: Fin — Conferido em 2026-10-18.

GET /v1/balances mostra o caixa da sua operação no Dracma. O campo que sustenta um novo saque não é available: é o caixa livre, que é available menos pending_out. Esta página explica cada campo, quando ele muda e o que acontece quando o caixa livre acaba.

O que é

Campo Significado Observação
available Dinheiro da operação que entrou e ainda não saiu. Inclui o valor reservado para saques em andamento. Não é "o quanto você pode sacar".
pending_out Valor reservado para saques que o Dracma está enviando ao PSP. Já está contado dentro de available.
pending_in Dinheiro já recebido e ainda não creditado, por depósitos em under_review, pending_compliance ou frozen. Informativo. Não entra em available.
as_of Instante da leitura, em UTC. Cada chamada lê o valor atual.

O caixa livre é:

caixa livre = available - pending_out

Ele é o que o Dracma confere antes de aceitar e de enviar um saque. Faça a mesma conta no seu lado, com inteiros na menor unidade.

Cuidado com available

Quem lê available como saldo gastável promete saques que o caixa não cobre. Use sempre available - pending_out.

Quando usar

  • Antes de prometer um saque ao jogador, para saber se há caixa livre para ele.
  • Em um alerta contínuo de caixa baixo (leia GET /v1/balances periodicamente, a cada poucos minutos).
  • Ao investigar um saque parado em approved por falta de caixa.

Como funciona

  1. O depósito pago aumenta available pelo valor cheio. pending_out não muda.
  2. Quando o Dracma prepara o envio de um saque ao PSP, ele reserva o valor: pending_out sobe e available fica igual. O caixa livre cai.
  3. Quando o PIX é liquidado, available e pending_out caem o valor do saque. O caixa livre não muda de novo (ele já tinha caído na reserva).
  4. Se o envio falha de forma definitiva, a reserva é liberada: pending_out cai e o caixa livre volta.

pending_out só existe a partir do envio. Um saque em requested, under_review ou approved ainda não reservou nada. Vários saques aprovados podem, juntos, somar mais que o caixa livre. Quem não consegue reservar na hora do envio fica approved e gera alerta no Dracma (veja Ciclo do saque).

Leitura:

  • Cada moeda habilitada na operação aparece, mesmo sem movimento (zerada).
  • O Dracma lê o caixa no livro da operação no momento da chamada. Se o livro estiver fora, a resposta é 503 retryable.

Exemplos

Uma operação com R$ 1.500,00 em caixa, dos quais R$ 900,00 estão reservados para saques em envio, e um depósito de R$ 2.500,00 em revisão:

{
  "data": [
    {
      "available": { "amount": "150000", "currency": "BRL" },
      "pending_in": { "amount": "250000", "currency": "BRL" },
      "pending_out": { "amount": "90000", "currency": "BRL" },
      "as_of": "2026-10-18T15:00:00Z"
    }
  ]
}

Caixa livre: 150000 - 90000 = 60000, ou R$ 600,00. Um saque de R$ 700,00 pedido agora recebe 422 insufficient_operation_balance.

Erros e casos de borda

Saque sem caixa livre

Situação O que o Dracma faz
Na criação, o caixa livre é menor que o valor 422 insufficient_operation_balance. Nenhum saque é criado: devolva a reserva do jogador. Você pode tentar mais tarde com uma Idempotency-Key e um external_id novos.
No envio, o caixa livre ficou menor que o valor O saque continua approved, o Dracma alerta e tenta de novo depois.
O Dracma não consegue ler o caixa (livro fora do ar) O saque entra em under_review com o motivo BALANCE_UNAVAILABLE. Na dúvida, o Dracma nunca libera.

Caixa livre negativo

O caixa livre pode ficar negativo quando um depósito já creditado é estornado ou sofre chargeback e há saques reservados. O valor sai de available, e pending_out continua igual.

  • Enquanto o caixa livre for negativo, todo novo saque recebe 422 insufficient_operation_balance.
  • Estorno e chargeback de depósito só acontecem no sandbox hoje. Veja Devoluções, estornos e disputas.
  • Um depósito returned nunca foi creditado, então não reduz o caixa.

O Dracma não mostra o saldo no PSP

Não disponível

O Dracma não expõe saldo por PSP nem por conexão. GET /v1/balances não aceita filtro de PSP, e o painel mostra apenas a posição da operação. Você nunca vê o saldo da conta bancária do PSP.

Caixa inicial e aporte

Não disponível

O Dracma não oferece aporte de caixa. Não há rota, painel ou transferência que adicione saldo à operação. O caixa só cresce por depósitos pagos e por devoluções de saque. Se você precisa pagar saques antes de ter depósitos, combine o procedimento com o Dracma antes do go-live.

No go-live, o item "caixa inicial conferido" significa conferir o que GET /v1/balances mostra depois dos primeiros depósitos. Veja Checklist de go-live.

pending_compliance e frozen

pending_in soma o valor pago (ou, se ainda não houver, o valor pedido) dos depósitos em under_review, pending_compliance e frozen. Os dois últimos estados existem na máquina do depósito, mas nenhum caminho do PIX leva um depósito até eles hoje. Na prática, pending_in é a soma dos depósitos em revisão. Trate os dois estados como não terminais, sem efeito de dinheiro, se algum dia aparecerem.

Faixa "Saques em verificação"

Quando o painel mostra a faixa "Saques em verificação", novos saques da operação podem demorar mais que o normal. Os depósitos seguem normalmente e o caixa não muda. Veja Ciclo do saque e Painel: saldos e caixa.

Veja também