Implement retries in Automatic Pix

Use retries to attempt again the debit of an Automatic Pix charge that was not settled on the due date.

Extra-day retries are triggered by your integration and follow the policy configured in the authorization.

Before you start

The authorization must be created with:

{
  "retryPolicy": "ALLOW_THREE_IN_SEVEN_DAYS"
}

If retryPolicy is NOT_ALLOWED or is not configured to allow retries, it will not be possible to enable them later for that authorization.

See the endpoint Create an authorization.

How it works

There are two types of retry:

The intraday retry does not count toward the extra-day retry limit.

1. Enable retries

Configure retryPolicy when creating the authorization:

{
  "retryPolicy": "ALLOW_THREE_IN_SEVEN_DAYS"
}

This value corresponds to the 3R_7D policy.

It allows:

• up to 3 retries on different dates;
• within 7 calendar days after the original due date;
• only before the next recurrence cycle;
• always with the same amount as the original charge.

The command must be sent by 11:59 PM on the day before the new settlement date.

2. Create a retry

After the original instruction fails, use the ID of the refused instruction:

POST /v3/pix/automatic/paymentInstructions/{id}/retries

Provide the new date:

{
  "dueDate": "2027-01-15"
}

See the endpoint: Create payment instruction retry.

Expected result

When the request is accepted, Asaas creates a new payment instruction.

Use purpose to identify its origin:

The retryAttempt field identifies the retry number.

Rules for the new attempt

The retry will be rejected if:

• it exceeds the limit of 3 attempts;
• dueDate exceeds the 7 allowed days;
• the date reaches or goes beyond the next cycle;
• the command is sent on the same day as the desired settlement;
• the authorization does not allow retries.

Business errors in these scenarios return HTTP 400.

3. Track the result

After creating the retry, track the processing via Webhook.

Use:

• purpose to differentiate the original instruction from the retry;
• retryAttempt to identify which attempt is being processed.

Do not create the next retry before knowing the result of the current attempt.

To see the scheduling, confirmation, refusal, and cancellation sequences, see Automatic Pix Webhook Flows.

To interpret a refusal, see Refusal Reasons.

Payment by another method

While there is an active instruction, the payer can settle the charge by another method until the day before the settlement date.

When this happens, the automatic instruction is canceled to prevent a new debit.

Payment by another method is blocked in the window:

10 PM on D-1 until settlement day D

Cancellation

It is not possible to individually cancel a retry that has already been created.

Canceling the authorization ends the pending schedules linked to the recurrence.

If the cancellation performed by Asaas occurs after 10 PM, schedules from D+2 onward will be canceled.

When retries are exhausted

After the last unsuccessful attempt:

There are no more pending automatic instructions for that charge, but the recurrence continues in the following cycles.

The creation of the next charges follows the authorization's paymentCreationMode:

• MANUAL: your application creates the charge for the next cycle;
• SUBSCRIPTION: the subscription generates the charge automatically.

To retrieve the linked charge, query the instruction and use paymentId:

See the endpoint Retrieve a single payment instruction.

The overdue charge can then be handled through the payment methods available on the invoice. When the payment is confirmed, your integration will receive the PAYMENT_CONFIRMED event as usual.

Next steps

• See the reference for creating a retry
• Retrieve a payment instruction
• Track the Webhook Flows
• Learn about the Refusal Reasons
• See the Automatic Pix events
• See the Automatic Pix FAQ