Eventos para bloqueios de saldo

Receba notificações em tempo real sempre que um valor for bloqueado ou desbloqueado no saldo da sua conta

Use os eventos de bloqueio de saldo para identificar valores bloqueados ou desbloqueados na conta sem consultar o extrato continuamente.

Esses eventos permitem reagir a retenções causadas por disputas Pix, processos judiciais ou bloqueios administrativos.

Eventos disponíveis

Evento	Quando ocorre	Tratamento na integração
`BALANCE_VALUE_BLOCKED`	Um valor é bloqueado no saldo da conta.	Registre a retenção e atualize a conciliação para refletir o valor indisponível.
`BALANCE_VALUE_UNBLOCKED`	Um valor previamente bloqueado é liberado.	Reverta a retenção correspondente e atualize a conciliação para refletir o retorno do valor ao saldo disponível.

Identifique a origem do bloqueio

O campo balance.type informa a origem do bloqueio.

`balance.type`	Origem
`PIX_INFRACTION`	Bloqueio originado pelo Mecanismo Especial de Devolução (MED) do Pix.
`JUDICIAL`	Bloqueio originado por processo judicial.
`ADMINISTRATIVE`	Bloqueio realizado internamente pela equipe do Asaas.

Utilize esse campo para definir o tratamento da retenção na sua conciliação.

Payload do evento

A notificação é enviada via POST com o evento e os dados do bloqueio.

{
  "id": "evt_6561b631fa5580caadd00bbe3b858607&9193",
  "event": "BALANCE_VALUE_BLOCKED",
  "dateCreated": "2024-10-16 11:11:04",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "balance": {
    "value": 1234.56,
    "date": "2025-09-03",
    "description": "Bloqueio de saldo referente a disputa Pix.",
    "type": "PIX_INFRACTION"
  }
}

Campos importantes do payload

Campo	Descrição
`id`	Identificador único do evento. Utilize-o para idempotência.
`event`	Identifica se o valor foi bloqueado ou desbloqueado.
`account.id`	Identificador da conta afetada.
`balance.value`	Valor relacionado ao bloqueio ou desbloqueio.
`balance.date`	Data relacionada ao evento de saldo.
`balance.description`	Descrição do bloqueio ou desbloqueio.
`balance.type`	Origem do bloqueio.

Como tratar os eventos

Ao receber um evento:

identifique a conta pelo campo account.id;
utilize event para diferenciar bloqueio de desbloqueio;
utilize balance.type para identificar a origem;
persista o id do evento para impedir processamento duplicado;
atualize sua conciliação com balance.value;
responda HTTP 200 após confirmar a persistência e processe regras adicionais de forma assíncrona.

Os Webhooks seguem o modelo at least once, portanto o mesmo evento pode ser enviado mais de uma vez.

Consulte como implementar idempotência em Webhooks.

Para acompanhar novos bloqueios e desbloqueios, utilize os Webhooks em vez de consultar repetidamente o extrato. O extrato pode continuar sendo utilizado para consulta histórica e conciliação sob demanda.

🚧
Atenção

Com a entrada de novos produtos e funções dentro do Asaas, é possível que novos atributos sejam incluídos no Webhook. É muito importante que seu código esteja preparado para não gerar exceções caso o Asaas devolva novos atributos não tratados pela sua aplicação, pois isso poderá causar interrupção na fila de sincronização.

Enviaremos um e-mail e avisaremos em nosso Discord quando novos campos forem incluídos no Webhook. O disparo será feito para o e-mail de notificação definido nas configurações do webhook.

Próximos passos

Updated 14 days ago

Did this page help you?