Saldo e conciliação

Os números por ativo

GET /integration/v1/balances

[
  {
    "asset": "BRL",
    "available": "1500.00",
    "held": "500.00",
    "receivable": "320.75",
    "reserve": "16.03",
    "blocked": "0.00",
    "owed": "0.00",
    "total": "2336.78"
  }
]

Campo	O que é	Sacável
available	disponível	sim
held	retido por um saque em andamento	não
receivable	a receber de cartão, ainda não liquidado	não
reserve	reserva contra contestação, com data para liberar	não
blocked	bloqueado pelo banco por uma contestação de PIX (MED); continua sendo seu	não
owed	o que a conta deve e o saldo não cobriu (por exemplo, uma contestação de cartão maior que o saldo)	—

total é a soma de available, held, receivable e reserve. owed fica fora do total: as próximas entradas pagam esse valor antes de virar disponível.

Os números são mostrados separados de propósito. Só o disponível faria você concluir que sumiu dinheiro; só o total faria você tentar sacar o que não pode.

Faça cache por alguns segundos. Em fluxo normal o saldo não muda mais rápido que isso, e consultar em laço só consome o seu teto de requisições.

Extrato

GET /integration/v1/statement

Um lançamento por linha, com o valor, o ativo, o instante e a transação que o originou. É a fonte para conciliar contra o seu próprio livro.

Concilie por extrato, não por webhook. O webhook é o aviso; o extrato é o fato. Se um aviso se perdeu — o seu servidor esteve fora, a entrega esgotou as retentativas —, o lançamento está lá do mesmo jeito.

Um roteiro de conciliação que funciona

1. Puxe o extrato do período.
2. Case cada lançamento com o seu pedido pelo id da cobrança ou do saque.
3. O que sobrar do seu lado são pedidos que você acha que foram pagos e não foram — normalmente confirmação feita no retorno do navegador em vez de no webhook.
4. O que sobrar do nosso lado são pagamentos que você não registrou — normalmente webhook perdido, e é isso que a conciliação existe para pegar.

Rodar isso uma vez por dia é o que transforma um webhook perdido de prejuízo em inconveniência.

Lançamento confirmado ou em processamento

Cada linha do extrato (GET /integration/v1/statement) traz settlement:

Valor	O que significa
confirmed	conferido com o banco
processing	só em conta bancária própria: o lançamento é posterior à última conferência com o banco e vira confirmed na próxima

Concilie pelo confirmed. Uma linha processing já está no saldo, mas ainda não foi batida com o extrato do banco.