Understand the Automatic Pix Webhook flows

Track the lifecycle of Automatic Pix authorizations and payment instructions through the events sent via Webhook.

This page presents the expected sequences of events. To see all events, payloads, and returned fields, go to Events for Automatic Pix.

Before you start

Before tracking the flows:

• implement the creation of the authorization and of the recurring charges;
• configure a Webhook to receive Automatic Pix events.

See:

• Automatic Pix Implementation
• Webhooks
• Events for Automatic Pix

Authorization flow

In Journey 3, authorization activation happens in two steps: the payment of the initial charge is completed and then the payer's institution sends Asaas the authorization confirmation.

The authorization may be refused when:

• the QR Code expires without payment or the payer does not complete the process;
• the initial payment is completed, but the payer's institution does not send the authorization confirmation.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PIX_AUTOMATIC_RECURRING<br/>AUTHORIZATION_CREATED"] --> B{"Was the first payment<br/>completed?"}

    B --> BSim(("Yes"))
    B --> BNao(("No"))

    BSim --> C["PAYMENT_CREATED"]
    C --> D["PAYMENT_RECEIVED"]
    D --> G{"Did the payer's institution<br/>confirm the authorization?"}

    G --> GSim(("Yes"))
    G --> GNao(("No"))

    GSim --> E["PIX_AUTOMATIC_RECURRING<br/>AUTHORIZATION_ACTIVATED"]
    GNao --> F2["PIX_AUTOMATIC_RECURRING<br/>AUTHORIZATION_REFUSED"]

    BNao --> F["PIX_AUTOMATIC_RECURRING<br/>AUTHORIZATION_REFUSED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B,G decisao
    class C,D validacao
    class E sucesso
    class F,F2 analise

    class BSim,GSim respostaSim
    class BNao,GNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1,6 stroke:#22C55E,stroke-width:4px
    linkStyle 2,7 stroke:#EF4444,stroke-width:4px

With the authorization in ACTIVE, new recurring charges can be linked to it.

Authorization termination

After activation, also track the events that end the recurrence:

When PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED occurs, the authorization object reports:

• cancellationReason: reason for the authorization cancellation;
• cancellationDate: date the cancellation occurred.

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

The PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIRED event represents the termination of the authorization upon reaching its finishDate and does not return cancellationReason.

This scenario is different from ANALYSIS_EXPIRATION, which is a cancellation reason and may be returned in authorization.cancellationReason in the PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED event.

When an authorization is canceled, already scheduled instructions may also be canceled.

Payment instruction flow

When you create a charge linked to an active authorization, Asaas generates a payment instruction for the payer's bank.

The instruction may be refused during scheduling or after it has been scheduled.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PIX_AUTOMATIC_RECURRING<br/>PAYMENT_INSTRUCTION<br/>CREATED"]

    B --> C{"Was the scheduling<br/>accepted?"}

    C --> CSim(("Yes"))
    C --> CNao(("No"))

    CSim --> D["PIX_AUTOMATIC_RECURRING<br/>PAYMENT_INSTRUCTION<br/>SCHEDULED"]

    CNao --> E["PIX_AUTOMATIC_RECURRING<br/>PAYMENT_INSTRUCTION<br/>REFUSED"]

    D --> F{"Was the payment<br/>settled?"}

    F --> FSim(("Yes"))
    F --> FNao(("No"))

    FSim --> G["PAYMENT_CONFIRMED"]

    FNao --> H["PIX_AUTOMATIC_RECURRING<br/>PAYMENT_INSTRUCTION<br/>REFUSED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class C,F decisao
    class B,D validacao
    class G sucesso
    class E,H analise

    class CSim,FSim respostaSim
    class CNao,FNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 2 stroke:#22C55E,stroke-width:4px
    linkStyle 3 stroke:#EF4444,stroke-width:4px
    linkStyle 7 stroke:#22C55E,stroke-width:4px
    linkStyle 8 stroke:#EF4444,stroke-width:4px

A refused instruction may indicate a failure in scheduling or settlement, such as insufficient balance or limit at the payer's bank.

See Refusal Reasons to identify the expected behavior in each scenario.

Instruction cancellation

In addition to refusals, a scheduled instruction may be canceled.

If the charge is paid by another method, the automatic instruction is canceled to prevent a new execution.

How to handle the events

When you receive an event:

1. use the id to avoid duplicate processing;
2. link the returned resource to your application's records;
3. update the internal state according to the event received;
4. query the resource through the API when you need to confirm its current state.

To learn about the specific payloads and fields for authorizations, instructions, and eligibility, see Events for Automatic Pix.

Next steps

• See the Automatic Pix events and payloads
• Learn about the Refusal Reasons
• Implement the retry process
• Understand the paused queue behavior
• See the Automatic Pix FAQ