Implementation

This guide presents the recommended integration flow for Automatic Pix using Journey 3, where the payer grants consent for future recurring payments during the settlement of the first payment.

The implementation consists of two main stages:

1. Creating the authorization with an immediate QR Code.
2. Creating recurring charges linked to the authorization.

📘

Important

Future recurring charges depend on an active authorization.

Therefore, the first step of the integration must always be the creation of the authorization.

1. Create an authorization with an immediate QR Code

Creating the authorization is the first step of the flow.

Your application must call the API to generate a QR Code containing both the information required for the first payment and the consent data for future recurring charges.

See the complete endpoint reference: Create authorization with immediate QR Code

When consuming this endpoint, a Pix copy-and-paste code (payload) will be generated and must be presented to the payer.

Once the payment is completed, the authorization becomes active and can be used for future recurring charges.

Conciliation identifier

The response contains the immediateQrCode object, which includes the conciliationIdentifier.

This same identifier will later be included in the corresponding payment, allowing your application to safely correlate the original authorization with the settled payment.

Authorization identifier

The response also returns the authorization id.

🚧

Important

Store the authorization id.

This identifier is required to:

• create recurring charges;
• associate future payments with the authorization;
• track authorization events;
• process Automatic Pix webhooks.

Monitoring through webhooks

Asaas provides webhooks that allow your application to receive real-time notifications about authorization events and payment instruction events.

These events are essential for keeping the integration synchronized and monitoring status changes asynchronously.

❗️

Webhooks

See the available examples and events in the Automatic Pix webhook events section.

2. Create recurring charges

After the authorization reaches the ACTIVE status, your application can begin creating recurring charges.

On the due date, the debit will be automatically executed in the payer's account.

To create a charge, use the charge creation endpoint and inform the pixAutomaticAuthorizationId field in the request body, using the identifier obtained during the authorization step.

See the complete endpoint reference: Create charge with Automatic Pix

Dependency on authorization status

📘

Important

Charges should only be created after the authorization reaches the ACTIVE status.

An authorization that has not yet been activated, has expired, or has been cancelled cannot be used for future recurring charges.

Time window before the due date

📘

Important

Payment instructions must respect an interval of 2 to 10 business days before the charge due date.

If your application attempts to create a charge outside this window, the API will return an exception.

This rule ensures that the payment instruction reaches the payer's institution within the period established by the Automatic Pix rules.

Typical implementation flow

Create authorization with immediate QR Code
↓
Present the QR Code to the payer
↓
Initial payment is completed
↓
Authorization becomes ACTIVE
↓
Store authorization ID
↓
Create recurring charges
↓
Send payment instructions
↓
Automatic settlement on due dates

Important behaviors

• The first payment activates the authorization.
• Future charges depend on an active authorization.
• The authorization identifier should be stored permanently.
• Cancellation or expiration of the authorization prevents future charges.
• Payment processing occurs asynchronously and should be monitored through webhooks.

Best practices

📘

Recommended

• Store the authorization id.
• Use the conciliationIdentifier for reconciliation.
• Wait for the ACTIVE status before creating charges.
• Implement webhooks to monitor events.
• Handle authorization cancellation and expiration scenarios.
• Respect the 2 to 10 business day interval before the due date.

Recommended next steps

After implementing the flow, we recommend consulting:

• Automatic Pix webhook events.
• Automatic Pix webhook flows.
• Refusal reasons.
• Create authorization with immediate QR Code.
• Create charges with Automatic Pix.
• Webhook configuration.