Bloqueios de saldo
Um bloqueio (hold) trava parte do saldo disponível da conta no liquidante. O valor continua na conta, mas sai do available do GET /balance até o bloqueio ser liberado para outra conta CorpX ou cancelado.
Escrita só por M2M, com o escopo holds.write. Criar e liberar passam pelas travas de cashout e pelo PIN de transação, como qualquer saída. Leitura aceita read, holds.read ou holds.write.
Ciclo de vida
Liberação parcial não existe: cancele e crie outro bloqueio. Bloqueio criado por uma ordem P2P (reason: p2p_order) só é liberado ou cancelado pela própria ordem e responde 409 hold_managed_by_order nas rotas acima.
O que está travado agora
GET .../holds?status=held lista só os bloqueios que ainda seguram saldo no liquidante: os active e os releasing ou cancelling cuja trava ainda não foi desfeita. A soma deles é o heldAmount do GET /balance, então a lista explica o saldo travado linha a linha.
Origem do bloqueio
Bloqueio criado por uma ordem P2P traz source, na lista e na consulta:
deadlineAté o prazo que corre agora na ordem (nullem disputa ou status final).- Nos bloqueios de ordem, as contas de destino (vendedor e intermediação) não aparecem, e
lastErrorsai como código público. - Bloqueio criado pela API, sem ordem, não tem
source. Se a leitura da ordem falhar, o campo só some.
Respostas assíncronas
202na criação: o liquidante não confirmou a trava. O hold ficaunknown_lockaté a reconciliação. Não reenvie com outra chave antes de consultar o saldo.202na liberação ou no cancelamento: a operação continua. Consulte o hold ou espere o webhook.
Webhooks
Códigos de erro na seção Bloqueios de saldo de Tratamento de Erros.