Balance block events

Receive real-time notifications whenever an amount is blocked or unblocked in your account balance

Use balance block events to identify amounts blocked or unblocked in the account without continuously querying the statement.

These events let you react to holds caused by Pix disputes, legal proceedings or administrative blocks.

Available events

Event	When it occurs	Handling in the integration
`BALANCE_VALUE_BLOCKED`	An amount is blocked in the account balance.	Record the hold and update the reconciliation to reflect the unavailable amount.
`BALANCE_VALUE_UNBLOCKED`	A previously blocked amount is released.	Reverse the corresponding hold and update the reconciliation to reflect the amount returning to the available balance.

Identify the origin of the block

The balanceData.type field indicates the origin of the block.

`balanceData.type`	Origin
`PIX_INFRACTION`	Block originated by the Pix Special Return Mechanism (MED).
`JUDICIAL`	Block originated by a legal proceeding.
`ADMINISTRATIVE`	Block applied internally by the Asaas team.
`CONTRACTUAL_EFFECT`	Block due to settlement of a contractual effect (receivables reservation).

Use this field to define how the hold is handled in your reconciliation.

Event payload

The notification is sent via POST with the event and the block data.

{
  "id": "evt_6561b631fa5580caadd00bbe3b858607&9193",
  "event": "BALANCE_VALUE_BLOCKED",
  "dateCreated": "2024-10-16 11:11:04",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "balanceData": {
    "value": 1234.56,
    "date": "2025-09-03",
    "description": "Balance block related to a Pix dispute.",
    "type": "PIX_INFRACTION",
    "paymentId": "pay_123456789"
  }
}

Important payload fields

Field	Description
`id`	Unique identifier of the event. Use it for idempotence.
`event`	Identifies whether the amount was blocked or unblocked.
`account.id`	Identifier of the affected account.
`balanceData.value`	Amount related to the block or unblock.
`balanceData.date`	Date related to the balance event.
`balanceData.description`	Description of the block or unblock.
`balanceData.type`	Origin of the block.
`balanceData.paymentId`	Charge related to the block, when there is one.

The paymentId attribute identifies the charge related to the block/unblock, when applicable. It is always present in the payload, but its value will be null when the block is not associated with a specific charge, which always happens for the JUDICIAL and ADMINISTRATIVE types, and may also occasionally happen for PIX_INFRACTION and CONTRACTUAL_EFFECT if there is no charge linked to the transaction.

How to handle the events

When receiving an event:

identify the account through the account.id field;
use event to distinguish a block from an unblock;
use balanceData.type to identify the origin;
persist the event id to prevent duplicate processing;
update your reconciliation with balanceData.value;
respond HTTP 200 after confirming persistence and process additional rules asynchronously.

Webhooks follow the at least once model, so the same event may be sent more than once.

See how to implement idempotence in Webhooks.

To track new blocks and unblocks, use Webhooks instead of repeatedly querying the statement. The statement can still be used for historical queries and on-demand reconciliation.

🚧
Attention

As new products and features are added to Asaas, new attributes may be included in the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes that your application does not handle, as this may interrupt the sync queue.

We will send an email and announce on our Discord when new fields are added to the Webhook. The email will be sent to the notification email address defined in the webhook settings.

Next steps

Updated 11 days ago

Did this page help you?