Automatic Pix events

Use Automatic Pix events to track changes in eligibility, authorizations and payment instructions.

To follow the sequences between these events and the payment events, see Automatic Pix Webhook flows.

Available events

Eligibility

Authorizations

Payment instructions

Account eligibility

The PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED event reports changes in the account's eligibility.

eligibility.status can be:

{
  "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": []
  }
}

Authorizations

In authorization events, the authorization object indicates the current state of the recurrence.

authorization.status can be:

The example below shows the main fields of the event. To see the complete authorization structure, go to Retrieve a single authorization.

{
  "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"
    }
  }
}

When the authorization is cancelled, the PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED event reports the cancellation date and reason in authorization.cancellationDate and authorization.cancellationReason.

Example:

{
  "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"
  }
}

See Automatic Pix authorization cancellation reasons to learn the possible values of authorization.cancellationReason.

To understand the sequence between creation, activation, refusal, cancellation and expiration, see Automatic Pix Webhook flows.

Payment instructions

Instructions represent the processing of a recurring charge at the payer's institution.

In the events on this page, paymentInstruction.status can be:

{
  "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"
    }
  }
}

Use paymentInstruction.paymentId to relate the instruction to the charge and paymentInstruction.authorization.id to identify the originating authorization.

The instruction resource may also show DONE as its current state in the API. The financial completion of the charge must be tracked through the payment events defined in the Automatic Pix flow.

See the reference for a payment instruction.

Important fields

Event

To interpret authorization.cancellationReason, see Automatic Pix authorization cancellation reasons.

Eligibility

Authorization

Payment instruction

How to handle the events

When receiving an event:

1. use event to identify the resource and the change that occurred;
2. persist the id before processing to avoid duplicates;
3. relate the eligibility, authorization or instruction to your application's records;
4. update the internal state according to the payload received;
5. respond HTTP 200 after persisting the event;
6. process additional rules asynchronously.

Webhooks follow the at least once model, so the same event may be resent. Use the id to implement idempotence.

When using authToken, validate the asaas-access-token header received in the Webhook.

See how to implement idempotence in Webhooks.

Next steps

• Follow the Automatic Pix Webhook flows
• Implement Automatic Pix
• Interpret the refusal reasons
• Implement retries in Automatic Pix
• Implement idempotence in Webhooks
• Monitor the Webhook Logs