Eventos para Pix Automático

Use os eventos do Pix Automático para acompanhar alterações de elegibilidade, autorizações e instruções de pagamento.

Para acompanhar as sequências entre esses eventos e os eventos das cobranças, consulte Fluxos de Webhook do Pix Automático.

Eventos disponíveis

Elegibilidade

Autorizações

Instruções de pagamento

Elegibilidade da conta

O evento PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED informa alterações na elegibilidade da conta.

eligibility.status pode assumir:

{
  "id": "evt_ID",
  "event": "PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED",
  "dateCreated": "2026-03-05 08:24:11",
  "account": {
    "id": "accountId",
    "ownerId": null
  },
  "eligibility": {
    "status": "INELIGIBLE",
    "ineligibleReasons": []
  }
}

Autorizações

Nos eventos de autorização, o objeto authorization informa o estado atual da recorrência.

authorization.status pode assumir:

{
  "event": "PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED",
  "authorization": {
    "id": "d51008fa-e28e-4823-82b4-4b1fcf485229",
    "status": "ACTIVE",
    "customerId": "cus_000006869125",
    "frequency": "MONTHLY",
    "value": 2.00,
    "startDate": "2025-08-01",
    "finishDate": "2028-01-01",
    "immediateQrCode": {
      "conciliationIdentifier": "ASAAS000000000000000000000000550ASA",
      "expirationDate": "2025-07-24 18:00:20"
    }
  }
}

Para entender a sequência entre criação, ativação, recusa, cancelamento e expiração, consulte Fluxos de Webhook do Pix Automático.

Instruções de pagamento

As instruções representam o processamento de uma cobrança recorrente na instituição do pagador.

Nos eventos desta página, paymentInstruction.status pode assumir:

{
  "event": "PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED",
  "paymentInstruction": {
    "id": "f6559451-cb41-4ec6-8487-2cda59a5f184",
    "status": "SCHEDULED",
    "dueDate": "2024-10-04",
    "paymentId": "pay_080225913252",
    "authorization": {
      "id": "c6b180f0-2196-454c-ac7e-72d662286bd1"
    }
  }
}

Utilize paymentInstruction.paymentId para relacionar a instrução à cobrança e paymentInstruction.authorization.id para identificar a autorização de origem.

O recurso de instrução também pode apresentar DONE como estado atual na API. A conclusão financeira da cobrança deve ser acompanhada pelos eventos de cobrança previstos no fluxo do Pix Automático.

Consulte a referência de uma instrução de pagamento.

Campos importantes

Evento

Elegibilidade

Autorização

Instrução de pagamento

Como tratar os eventos

Ao receber um evento:

1. utilize event para identificar o recurso e a alteração ocorrida;
2. persista o id antes do processamento para evitar duplicidade;
3. relacione a elegibilidade, autorização ou instrução aos registros da sua aplicação;
4. atualize o estado interno conforme o payload recebido;
5. responda HTTP 200 após persistir o evento;
6. processe regras adicionais de forma assíncrona.

Os Webhooks seguem o modelo at least once, portanto o mesmo evento pode ser reenviado. Utilize o id para implementar idempotência.

Quando utilizar authToken, valide o header asaas-access-token recebido no Webhook.

Consulte como implementar idempotência em Webhooks.

Próximos passos

• Acompanhe os Fluxos de Webhook do Pix Automático
• Implemente o Pix Automático
• Interprete os motivos de recusa
• Implemente retentativas no Pix Automático
• Implemente idempotência em Webhooks
• Monitore os Logs de Webhooks