Skip to navigation

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

POST /holds ──► active ──► releasing ──► released (transferência interna)
│
└──► cancelling ──► cancelled (valor volta ao disponível)
unknown_lock: o liquidante não confirmou a trava; a CorpX reconcilia.
RotaO que faz
POST /v1/accounts/{accountId}/holdsTrava amount. Idempotency-Key obrigatória; a repetição exata devolve o mesmo hold com 200.
GET /v1/accounts/{accountId}/holdsLista, com filtro status (um status do ciclo de vida ou held).
GET /v1/accounts/{accountId}/holds/{holdId}Consulta um bloqueio.
POST .../holds/{holdId}/releaseTransfere o valor para to.accountId, com fee opcional para uma terceira conta. amount mais fee.amount tem de fechar o valor do hold.
POST .../holds/{holdId}/cancelDevolve o valor ao disponível. reason obrigatório.

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:

{
"holdId": "hld_6b0c2d1e-…",
"status": "active",
"amount": "1005.00",
"reason": "p2p_order",
"reference": "P2P ord_4235120236fa625f2a539d0c",
"source": {
"type": "p2p_order",
"orderId": "ord_4235120236fa625f2a539d0c",
"orderStatus": "crypto_sent",
"side": "buy",
"pair": "USDT_TRON",
"network": "tron",
"cryptoAmount": "196.29",
"price": "5.12",
"deadlineAt": "2026-11-01T15:10:00Z"
}
}
  • deadlineAt é o prazo que corre agora na ordem (null em disputa ou status final).
  • Nos bloqueios de ordem, as contas de destino (vendedor e intermediação) não aparecem, e lastError sai 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

  • 202 na criação: o liquidante não confirmou a trava. O hold fica unknown_lock até a reconciliação. Não reenvie com outra chave antes de consultar o saldo.
  • 202 na liberação ou no cancelamento: a operação continua. Consulte o hold ou espere o webhook.

Webhooks

EventoQuando
account.hold.createdO valor foi travado (active).
account.hold.releasedO valor foi transferido para a conta de destino (e a taxa, quando houver).
account.hold.cancelledO valor voltou ao disponível.

Códigos de erro na seção Bloqueios de saldo de Tratamento de Erros.