Implement Automatic Pix

Create the Automatic Pix authorization, track its activation, and configure how the charges for subsequent cycles will be generated.

Before you start

Before implementing:

• confirm that the account is eligible to use Automatic Pix;
• register the customer and store their ID;
• configure the Webhooks that will track the authorization and the charges.

To understand the journey before implementing, see Automatic Pix.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Define paymentCreationMode"] --> B["Create authorization"]
    B --> C["Present the QR Code"]
    C --> D["Payer makes the first payment"]
    D --> E["Wait for ACTIVE authorization"]
    E --> F{"How will the charges be created?"}

    F --> FManual(("MANUAL"))
    F --> FAutomatico(("SUBSCRIPTION"))

    FManual --> G["Application creates each charge"]
    FAutomatico --> H["Subscription generates the charges"]

    G --> I["Track the events via Webhook"]
    H --> I

    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 respostaManual fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaAutomatico fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px

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

    class FManual respostaManual
    class FAutomatico respostaAutomatico

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 5 stroke:#8B5CF6,stroke-width:4px
    linkStyle 6 stroke:#22C55E,stroke-width:4px

1. Choose the charge creation mode

Define paymentCreationMode when creating the authorization.

MANUAL is the default value.

To use SUBSCRIPTION, also provide value in the authorization.

Manual configuration example:

{
  "paymentCreationMode": "MANUAL"
}

Automatic configuration example:

{
  "paymentCreationMode": "SUBSCRIPTION",
  "value": 100.00
}

2. Create the authorization

Start the flow by creating an authorization with an immediate QR Code:

POST /v3/pix/automatic/authorizations

The immediateQrCode object represents the first payment and will be used to record the payer's consent.

See the endpoint Create an authorization.

Expected result

The response provides the QR Code for the first payment and the authorization id.

Store the id. It will be used to:

• query the authorization status;
• correlate events;
• create charges in MANUAL mode.

3. Wait for activation

Present the QR Code to the payer and wait for the first payment to be completed.

After the payment is confirmed, the payer's institution must send Asaas the authorization confirmation. With this confirmation, the status changes to ACTIVE.

Track this change via Webhook.

See the Automatic Pix Webhook Flows.

4. Process the recurring charges

The behavior depends on the chosen paymentCreationMode.

MANUAL

With the authorization in ACTIVE, your application must create each charge for the cycle:

POST /v3/payments

Provide the authorization ID in pixAutomaticAuthorizationId:

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 100.00,
  "dueDate": "YYYY-MM-DD",
  "pixAutomaticAuthorizationId": "AUTHORIZATION_ID"
}

See the endpoint Create new payment.

SUBSCRIPTION

In this mode, Asaas uses a subscription to automatically generate the charges linked to the authorization.

Do not manually create a new charge for each cycle.

The value field is required in the authorization when paymentCreationMode is SUBSCRIPTION.

See the available fields and rules in Create an authorization.

5. Track processing

Regardless of the chosen mode, track via Webhook:

• the authorization status;
• the creation and processing of instructions;
• the confirmation of charges;
• refusals and cancellations.

See Automatic Pix Webhook Flows.

For refusals, see Refusal Reasons.

Next steps

• Track the Webhook Flows
• Learn about the Refusal Reasons
• Implement the retry process
• Compare Automatic Pix and Subscriptions
• See the Automatic Pix FAQ