Eventos para movimentações internas

Receba notificações sobre créditos e débitos internos que ocorrem em sua conta

Use os eventos de movimentações internas para identificar créditos e débitos relacionados a operações entre contas Asaas, Split de Pagamentos e Avalista-Devedor.

Para acompanhar novas movimentações, utilize Webhooks em vez de consultar continuamente o extrato.

Eventos disponíveis

Evento	Quando ocorre
`INTERNAL_TRANSFER_CREDIT`	A conta recebe um crédito originado de uma movimentação interna.
`INTERNAL_TRANSFER_DEBIT`	A conta sofre um débito originado de uma movimentação interna. Atualmente, este evento é disparado apenas no fluxo de Avalista-Devedor.

O evento INTERNAL_TRANSFER_DEBIT não deve ser utilizado para acompanhar o débito de uma transferência direta entre contas Asaas.

Nesse cenário, acompanhe a operação pelos Eventos para transferências. A transferência pode ser criada pelo endpoint Transferir para conta Asaas.

Identifique a origem da movimentação

O campo internalTransferData.type informa a origem da movimentação.

`internalTransferData.type`	Origem
`INTERNAL_LOAN`	Movimentação relacionada à funcionalidade de Avalista-Devedor em operações com subcontas.
`SPLIT`	Crédito recebido referente a um Split de Pagamentos.
`INTERNAL_TRANSFER`	Crédito recebido de uma transferência direta de outra conta Asaas.

Utilize event para identificar se houve crédito ou débito e internalTransferData.type para identificar a origem da movimentação.

Payload do evento

A notificação é enviada via POST com o evento e os dados da movimentação interna.

{
  "id": "evt_6561b631fa5580caadd00bbe3b858607&9193",
  "event": "INTERNAL_TRANSFER_DEBIT",
  "dateCreated": "2024-10-16 11:11:04",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "internalTransferData": {
    "description": "Transferência enviada para regularização de saldo da conta Asaas",
    "value": -48.52,
    "date": "2025-09-03",
    "type": "INTERNAL_LOAN"
  }
}

Campos importantes do payload

Campo	Descrição
`id`	Identificador único do evento. Utilize-o para idempotência.
`event`	Identifica se a conta recebeu um crédito ou sofreu um débito.
`account.id`	Identificador da conta relacionada à movimentação.
`account.ownerId`	Identificador da conta raiz, quando aplicável.
`internalTransferData.description`	Descrição da movimentação.
`internalTransferData.value`	Valor da movimentação.
`internalTransferData.date`	Data da movimentação.
`internalTransferData.type`	Origem da movimentação interna.

Como tratar os eventos

Ao receber um evento:

identifique a conta pelo campo account.id;
utilize event para diferenciar crédito de débito;
utilize internalTransferData.type para identificar a origem da movimentação;
utilize internalTransferData.value e internalTransferData.date na conciliação;
persista o id do evento para impedir processamento duplicado.

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

Consulte como implementar idempotência em Webhooks.

Para consultar o histórico financeiro consolidado da conta, utilize o Extrato da conta. Para identificar novas movimentações internas, priorize os eventos desta página.

🚧
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?