Processo de retentativas (Jornada 3 API)

O processo de retentativas permite que você, como usuário recebedor (cliente Asaas), busque a liquidação de uma cobrança de Pix Automático que falhou no vencimento original, comandando novas tentativas de débito em datas posteriores — dentro dos limites definidos pelo arranjo Pix do Banco Central.

O objetivo é reduzir a inadimplência das cobranças recorrentes e aumentar o percentual de liquidação, sem precisar criar uma nova cobrança ou uma nova autorização.

Resumo

Para usar retentativas no Pix Automático:

1. Crie a autorização com retryPolicy = ALLOW_THREE_IN_SEVEN_DAYS.
2. Quando uma instrução falhar no vencimento, acione o endpoint de retentativa informando uma nova dueDate.
3. A regra permite até 3 tentativas em datas diferentes, dentro de 7 dias corridos após o vencimento original e antes do próximo ciclo da recorrência.

Os detalhes de cada passo, validações e webhooks estão nas seções seguintes.

Visão geral

Existem dois tipos de retentativa no Pix Automático. É importante entender a diferença, porque apenas a retentativa extradia é comandada por você via API.

Observação: a retentativa intradia obrigatória, também chamada de tentativa noturna, aplica-se em cada dia de retentativa extradia.

Fluxo de integração

O diagrama abaixo resume a jornada completa de uma retentativa extradia — desde o webhook que informa a falha no vencimento, passando pela chamada de API que comanda a nova tentativa, até a liquidação.

Os passos estão detalhados nas seções seguintes.

A política 3R_7D

A retentativa extradia é regida pela política regulatória conhecida como 3R_7D:

• 3R: no máximo 3 tentativas em datas diferentes para a mesma cobrança que falhou.
• 7D: as tentativas devem ocorrer dentro de 7 dias corridos, contados a partir da data de liquidação original.
• O limite de 7 dias não pode ultrapassar o dia imediatamente anterior ao início do próximo ciclo de cobrança.
• O valor de cada retentativa deve ser idêntico ao da cobrança original.
• O comando de cada retentativa deve ser enviado até as 23h59 do dia anterior à nova data prevista para liquidação.

Exemplo

Se a cobrança original venceu em 01/07/2026, as retentativas extradia podem ser comandadas para datas dentro dos 7 dias corridos seguintes, desde que não coincidam nem ultrapassem o início do próximo ciclo.

Para tentar liquidar a cobrança em 03/07/2026, o comando precisa ser enviado até 02/07/2026, às 23h59.

Nomenclatura — Banco Central × Asaas

3R_7D é o termo usado pelo Banco Central para descrever a política.

Na API do Asaas, essa mesma política é representada pelo enum ALLOW_THREE_IN_SEVEN_DAYS, informado no campo retryPolicy.

Sempre que este guia mencionar 3R_7D, refere-se à política representada por ALLOW_THREE_IN_SEVEN_DAYS na integração.

Quando você habilita a política, o Asaas registra a recorrência com permissão para retentativas e passa a aceitar instruções de retentativa para as cobranças daquela recorrência.

Importante: uma recorrência que não foi criada com a política de retentativa habilitada trata qualquer falha no vencimento como falha definitiva.

Não é possível habilitar retentativas posteriormente. A configuração deve ser realizada na criação da autorização.

Passo 1 — Habilitar a política na criação da autorização

A permissão para retentativas é definida no momento da criação da recorrência de Pix Automático, por meio do campo retryPolicy, do tipo string.

{
  "...": "demais campos da criação da recorrência",
  "retryPolicy": "ALLOW_THREE_IN_SEVEN_DAYS"
}

Comportamento por configuração

• retryPolicy ausente: padrão desabilitado. A recorrência é criada sem permissão para retentativas.
• retryPolicy = "ALLOW_THREE_IN_SEVEN_DAYS": a recorrência é criada com permissão para retentativas extradia.
• retryPolicy com valor inválido, como ALLOW_FIVE_IN_TEN_DAYS: a criação é rejeitada com erro HTTP 400.

Informação técnica: internamente, a habilitação reflete no idRecorrencia.

O segundo caractere será:

• R: permite retentativas;
• N: não permite retentativas.

Normalmente, você não precisa interpretar esse campo, mas ele pode aparecer em integrações que leem diretamente as mensagens do arranjo Pix.

Passo 2 — Acionar uma retentativa

Quando uma cobrança falhar no vencimento e você receber o evento de instrução recusada, poderá agendar uma nova tentativa informando a data desejada para o novo débito.

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

Corpo da requisição

{
  "dueDate": "2026-07-03"
}

Parâmetros

Exemplo de resposta

{
  "id": "{id}",
  "purpose": "RETRY_AFTER_DUE_DATE",
  "...": "demais campos da instrução de pagamento"
}

O campo purpose identifica a natureza da instrução de pagamento:

• SCHEDULE: instrução original;
• RETRY_AFTER_DUE_DATE: instrução de retentativa.

Esse campo permite diferenciar uma retentativa da cobrança original.

Ao aceitar a requisição, o Asaas gera uma nova instrução de pagamento para o PSP Pagador com a finalidade de agendamento NTAG, utilizada em retentativas motivadas por falta de saldo ou limite.

Nomenclatura — Banco Central × Asaas

NTAG é a finalidade do agendamento definida pelo Banco Central para retentativas por falta de saldo ou limite.

Na API do Asaas, ela corresponde ao purpose = RETRY_AFTER_DUE_DATE da instrução de pagamento.

Os dois termos representam o mesmo conceito, observado de lados diferentes da integração.

Validações aplicadas

A requisição é rejeitada se qualquer uma das regras abaixo for violada. Erros de negócio retornam o status HTTP 400.

Passo 3 — Acompanhar via webhooks

As retentativas usam o fluxo padrão de eventos de instrução de pagamento do Pix Automático.

Para diferenciar uma instrução de retentativa da instrução original, observe os seguintes campos no payload dos eventos:

Eventos envolvidos

Sequências esperadas

Retentativa paga com sucesso

PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
→ PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
→ PAYMENT_CONFIRMED

Retentativa agendada, mas recusada por falta de saldo na data

PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
→ PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED
→ PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED

A cobrança permanece pendente ou vencida. Se ainda houver tentativas disponíveis na regra 3R_7D, você poderá comandar a próxima retentativa.

Retentativa recusada imediatamente pelo PSP Pagador

PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED
→ PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED

Nesse caso, o evento PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED não é enviado.

Cancelamento da autorização com retentativa agendada

PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED
→ PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED

Cobrança paga por outro meio com instrução ativa

PAYMENT_CONFIRMED
→ PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED

Cancelamento de retentativas

A falha de uma instrução não cancela a autorização.

Se uma cobrança falhar no vencimento, com ou sem retentativas, a autorização segue ativa e as próximas cobranças da recorrência continuam sendo geradas normalmente.

Nenhum passo adicional é necessário do seu lado.

O usuário recebedor não pode cancelar pontualmente uma instrução de retentativa que já foi gerada.

Uma vez iniciado o processo, não é possível intervir naquela cobrança específica. A instrução seguirá o ciclo de tentativas e expirará conforme a política configurada.

O cancelamento ocorre apenas de forma indireta, por meio do cancelamento da autorização, que pode ser realizado:

• pelo pagador;
• pelo PSP Pagador;
• pelo Asaas.

O cancelamento da autorização cancela automaticamente todos os agendamentos pendentes, incluindo as retentativas extradia de D+1 em diante.

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

Recebimento por outro meio

O pagador pode quitar a cobrança por outro meio, como fatura, boleto ou Pix Copia e Cola, até o dia anterior ao vencimento de uma instrução ativa, seja ela original ou uma retentativa.

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

Você recebe o webhook:

PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED

O recebimento por outro meio fica bloqueado somente dentro da janela crítica:

A partir das 22h de D-1 até o dia do vencimento D.

Recuperação após o encerramento da retentativa

Quando todas as tentativas se esgotam sem sucesso, você recebe o webhook final:

PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED

Nesse momento:

• não existem mais tentativas disponíveis na política 3R_7D;
• a cobrança pai permanece com status Vencida;
• o Pix Automático deixa de ter instruções automáticas pendentes para aquela cobrança.

A partir desse ponto, você pode tratar a cobrança como qualquer outra cobrança vencida e continuar enviando o link de fatura, com boleto e Pix Copia e Cola, ao pagador.

Como não existe mais uma instrução automática pendente, não haverá cancelamento automático da instrução quando o pagamento for realizado por outro meio.

Estados esperados após o encerramento

Como cobrar por outro meio

1. Identifique a cobrança pai vinculada à instrução que falhou.

   O payload do webhook PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED traz o vínculo com a cobrança no campo payment.

   Alternativamente, você pode navegar a partir da autorização usando o endpoint de recuperação de uma única autorização de Pix Automático, localizar a subscription vinculada e listar suas cobranças em aberto.

2. Envie o link de fatura da cobrança ao pagador.

   O Asaas mantém o link ativo com boleto e Pix Copia e Cola após o encerramento da retentativa.

3. Aguarde a confirmação do pagamento.

   Quando o pagador quitar a cobrança por esse meio, você receberá normalmente o webhook:

   Text

   PAYMENT_CONFIRMED

Importante: as próximas cobranças da autorização não são afetadas.

Elas continuam sendo geradas nos ciclos seguintes, independentemente do desfecho desta cobrança específica.

Boas práticas e observações

• Reserve a janela de 7 dias ao definir a data final da recorrência.
  Se você configurar uma data final, adicione dias extras ao fim do contrato para que a última cobrança ainda tenha tempo hábil para utilizar os 7 dias da política 3R_7D.

• Não conte a tentativa intradia como uma das 3 tentativas.
  A tentativa noturna obrigatória do PSP Pagador é automática e independente das retentativas extradia comandadas por você.

• Trate a idempotência no seu sistema.
  Evite requisições concorrentes para criar a mesma retentativa. Comande uma tentativa por vez e aguarde a confirmação via webhook.

• Use os campos purpose e retryAttempt na conciliação.
  Esses campos permitem diferenciar a cobrança original das retentativas e definir ações automatizadas, como suspender um serviço após a terceira falha.

Referências

• Recuperar uma única instrução de pagamento de Pix Automático
• Criar retentativa de instrução de pagamento de Pix Automático
• Guia do Pix Automático