DiscordStatus
Guias / Guides

Automatic Pix Webhook Flows

This page presents the main Automatic Pix event flows and how they are delivered through Asaas Webhooks.

Webhooks allow your application to automatically track the lifecycle of authorizations and recurring charges without the need for constant API polling.

In addition to the event sequences themselves, it is important to understand the expected behaviors, dependencies between resources, and the operational scenarios involved.

When to use

Automatic Pix webhooks are recommended for integrations that need to:

  • update authorization statuses in real time;
  • identify when an authorization has been activated, expired, or cancelled;
  • track the creation and processing of payment instructions;
  • automatically update recurring charge statuses;
  • execute internal actions based on received events.

Flow dependencies

For recurring charge events to exist, the following conditions must be met:

  1. An Automatic Pix authorization must have been created.
  2. The authorization must be active.
  3. Charges must be created normally.
  4. Payment instructions must be sent to the payer's institution.

If the authorization is cancelled or expires, subsequent payment instructions may be automatically cancelled.

📘

Important

Charge events and payment instruction events depend on the existence of an active authorization.

Without a valid authorization, new schedules cannot be processed.

Integration best practices

📘

Recommended

  • Treat webhooks as asynchronous events.
  • Do not assume that different events will arrive at exactly the same time.
  • Use the event identifier to guarantee idempotency.
  • Always return HTTP 200 after processing the event.
  • Implement safe retry mechanisms to avoid duplicate processing.
  • Keep your endpoint available to receive delivery retries.

Important behaviors

⚠️

Important

  • The same event may be resent if delivery fails.
  • Events should be processed idempotently.
  • Events represent state transitions of authorizations and payment instructions.
  • Cancelling an authorization may result in the cancellation of related payment instructions.
  • Paying a charge through another method may cause the automatic payment instruction to be cancelled.

Authorization flows

Authorizations represent the permission granted by the payer to allow future recurring charges to be processed automatically.

Authorization successfully granted

Immediate QR Code created, payment completed, and authorization granted:

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
PAYMENT_CREATED
↓
PAYMENT_RECEIVED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED

After activation, future recurring charges can be processed automatically.

Authorization expired

Immediate QR Code created, payment completed, authorization granted, and later expired because the period defined in finishDate ended:

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
PAYMENT_CREATED
↓
PAYMENT_RECEIVED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIRED
📘

Important

Once the date defined in finishDate is reached, the authorization becomes invalid and future charges will no longer be processed.

QR Code expired without payment

QR Code created, but payment was not completed:

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_REFUSED

In this scenario, the authorization is not activated.

Cancellation performed by the payer

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
PAYMENT_CREATED
↓
PAYMENT_RECEIVED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED

After cancellation, future recurring charges are no longer processed.

Cancellation performed by the Asaas customer

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED
↓
PAYMENT_CREATED
↓
PAYMENT_RECEIVED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED

Regardless of who initiated the cancellation, the resulting behavior is the same.

Payment instruction flows

Payment instructions represent the schedules sent to the payer's institution to execute recurring charges.

Successful payment

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PAYMENT_CONFIRMED

The charge was successfully executed.

Failure due to insufficient balance or limit

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED

This scenario may occur due to insufficient balance or available limit at the payer's institution.

Scheduling refused by the payer's institution

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED

For example, operational failures may prevent the instruction from being scheduled.

Cancellation by the payer

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED

Cancellation by the Asaas customer

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED

Charge paid through another method

If the charge is paid manually, the automatic instruction is no longer necessary:

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PAYMENT_CONFIRMED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED
📘

Important

Receiving the payment through another method prevents the automatic charge from being executed again.

Authorization cancellation

When an authorization is cancelled, related payment instructions may also be cancelled:

PAYMENT_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
↓
PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED
↓
PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED

Operational impacts

Applications consuming Automatic Pix webhooks should consider that:

  • cancelling an authorization interrupts future charges;
  • authorization expiration prevents new schedules;
  • a cancelled instruction does not necessarily mean an operational failure, as it may be caused by a payment completed through another method;
  • events should be processed asynchronously and idempotently;
  • the final charge state should be determined by the received events, not solely by the existence of a payment instruction.

Next steps

After implementing Automatic Pix webhooks, we recommend consulting: