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:

O exemplo abaixo apresenta os principais campos do evento. Para consultar a estrutura completa da autorização, acesse Recuperar uma única autorização.

{
  "id": "evt_123456",
  "event": "PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED",
  "dateCreated": "2026-07-10 14:32:18",
  "account": {
    "id": "accountId",
    "ownerId": null
  },
  "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"
    }
  }
}

Quando a autorização for cancelada, o evento PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED informa a data e o motivo do cancelamento em authorization.cancellationDate e authorization.cancellationReason.

Exemplo:

{
  "id": "evt_123456",
  "event": "PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED",
  "dateCreated": "2026-06-30 07:02:35",
  "account": {
    "id": "accountId",
    "ownerId": null
  },
  "authorization": {
    "id": "cda9f932-9e89-469c-a6a7-1f0110e4d580",
    "value": null,
    "status": "CANCELLED",
    "payload": null,
    "frequency": "MONTHLY",
    "startDate": "31/12/2025",
    "contractId": "contractId",
    "customerId": "cus_000000000000",
    "finishDate": null,
    "originType": "IMMEDIATE_PAYMENT_AND_RECURRING_QR_CODE",
    "description": null,
    "retryPolicy": "NOT_ALLOWED",
    "encodedImage": null,
    "minLimitValue": null,
    "subscriptionId": null,
    "immediateQrCode": {
      "expirationDate": "03/01/2026 18:45:38",
      "conciliationIdentifier": "CONCILIATION_IDENTIFIER"
    },
    "cancellationDate": "30/06/2026",
    "cancellationReason": "REQUESTED_BY_PAYER_USER",
    "endToEndIdentifier": "END_TO_END_IDENTIFIER",
    "paymentCreationMode": "MANUAL"
  }
}

Consulte Motivos de cancelamento da autorização do Pix Automático para conhecer os possíveis valores de authorization.cancellationReason.

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

Para interpretar authorization.cancellationReason, consulte Motivos de cancelamento da autorização do Pix Automático.

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