Implemente retentativas no Pix Automático

Use retentativas para tentar novamente o débito de uma cobrança do Pix Automático que não foi liquidada no vencimento.

As retentativas extradia são comandadas pela sua integração e seguem a política configurada na autorização.

Antes de começar

A autorização deve ser criada com:

{
  "retryPolicy": "ALLOW_THREE_IN_SEVEN_DAYS"
}

Se retryPolicy for NOT_ALLOWED ou não for configurado para permitir retentativas, não será possível habilitá-las posteriormente para aquela autorização.

Consulte o endpoint Criar uma autorização.

Como funciona

Existem dois tipos de retentativa:

A retentativa intradia não conta no limite das retentativas extradia.

1. Habilite as retentativas

Configure retryPolicy durante a criação da autorização:

{
  "retryPolicy": "ALLOW_THREE_IN_SEVEN_DAYS"
}

Esse valor corresponde à política 3R_7D.

Ela permite:

• até 3 retentativas em datas diferentes;
• dentro de 7 dias corridos após o vencimento original;
• somente antes do próximo ciclo da recorrência;
• sempre com o mesmo valor da cobrança original.

O comando deve ser enviado até 23h59 do dia anterior à nova data de liquidação.

2. Crie uma retentativa

Após a falha da instrução original, utilize o ID da instrução recusada:

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

Informe a nova data:

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

Consulte o endpoint: Criar retentativa de instrução de pagamento.

Resultado esperado

Quando a solicitação for aceita, o Asaas cria uma nova instrução de pagamento.

Utilize purpose para identificar sua origem:

O campo retryAttempt identifica o número da retentativa.

Regras da nova tentativa

A retentativa será rejeitada se:

• exceder o limite de 3 tentativas;
• dueDate ultrapassar os 7 dias permitidos;
• a data atingir ou ultrapassar o próximo ciclo;
• o comando for enviado no mesmo dia da liquidação desejada;
• a autorização não permitir retentativas.

Erros de negócio nesses cenários retornam HTTP 400.

3. Acompanhe o resultado

Após criar a retentativa, acompanhe o processamento por Webhook.

Use:

• purpose para diferenciar a instrução original da retentativa;
• retryAttempt para identificar qual tentativa está sendo processada.

Não crie a próxima retentativa antes de conhecer o resultado da tentativa atual.

Para consultar as sequências de agendamento, confirmação, recusa e cancelamento, consulte Fluxos de Webhook do Pix Automático.

Para interpretar uma recusa, consulte Motivos de Recusa.

Pagamento por outro meio

Enquanto existir uma instrução ativa, o pagador pode quitar a cobrança por outro meio até o dia anterior à data de liquidação.

Quando isso ocorre, a instrução automática é cancelada para evitar um novo débito.

O pagamento por outro meio fica bloqueado na janela:

22h de D-1 até o dia da liquidação D

Cancelamento

Não é possível cancelar individualmente uma retentativa já criada.

O cancelamento da autorização encerra os agendamentos pendentes vinculados à recorrência.

Se o cancelamento realizado pelo Asaas ocorrer após as 22h, os agendamentos a partir de D+2 serão cancelados.

Quando as retentativas se esgotarem

Após a última tentativa sem sucesso:

Não existem mais instruções automáticas pendentes para aquela cobrança, mas a recorrência continua nos ciclos seguintes.

A criação das próximas cobranças segue o paymentCreationMode da autorização:

• MANUAL: sua aplicação cria a cobrança do próximo ciclo;
• SUBSCRIPTION: a assinatura gera a cobrança automaticamente.

Para recuperar a cobrança vinculada, consulte a instrução e utilize paymentId:

Consulte o endpoint Recuperar uma única instrução de pagamento.

A cobrança vencida pode então ser tratada pelos meios de pagamento disponíveis na fatura. Quando o pagamento for confirmado, sua integração receberá normalmente o evento PAYMENT_CONFIRMED.

Próximos passos

• Consulte a referência para criar uma retentativa
• Recupere uma instrução de pagamento
• Acompanhe os Fluxos de Webhook
• Conheça os Motivos de Recusa
• Consulte os eventos do Pix Automático
• Consulte o FAQ do Pix Automático