Motivos de Recusa

Interprete recusas do Pix Automático

Quando uma instrução de pagamento do Pix Automático for recusada, utilize o motivo retornado para definir o tratamento na sua aplicação.

As recusas podem ocorrer durante o agendamento ou a liquidação da cobrança e podem ser originadas pelo Asaas ou pela instituição financeira do pagador.

Quando utilizar

Consulte esta página quando:

uma instrução retornar REFUSED;
o evento PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED for recebido;
sua aplicação precisar identificar a causa da recusa;
for necessário decidir se o fluxo pode seguir para uma retentativa ou exige outra ação.

Como identificar a recusa

Quando a instrução estiver com status REFUSED, consulte o campo refusalReason para identificar o motivo.

Armazene o código original retornado pela API e faça o mapeamento para a mensagem ou ação correspondente na sua aplicação.

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

📘
Importante
Uma recusa não significa necessariamente falha da integração.
O motivo pode estar relacionado à conta do pagador, à autorização, às regras da recorrência ou ao processamento da instituição financeira.

Recusa identificada pelo Asaas

Motivo	Descrição
`PAYMENT_OVERDUE`	Cobrança vencida por ausência de saldo ou limite no momento do débito

Recusas retornadas pela instituição pagadora

Motivo	Descrição
`EXTERNAL_INSTITUTION_ERROR`	Erro na instituição financeira do pagador
`ACCOUNT_CLOSED`	Conta transacional encerrada
`ACCOUNT_BLOCKED`	Conta transacional bloqueada
`SAME_INSTITUTION_ERROR`	O agendamento não pode ser solicitado para contas que utilizam o mesmo participante liquidante do SPI
`MAXIMUM_AMOUNT_EXCEEDED`	Valor superior ao limite definido pelo pagador
`AMOUNT_MISMATCH`	Valor diferente do previsto na recorrência
`RECEIVER_CPF_CNPJ_MISMATCH`	CPF/CNPJ do recebedor divergente dos dados da recorrência
`PAYER_CPF_CNPJ_MISMATCH`	CPF/CNPJ do pagador divergente dos dados da autorização
`PARTICIPANT_NOT_REGISTERED`	Participante não cadastrado ou indisponível no SPI
`DUE_DATE_MISMATCH`	Vencimento incompatível com as regras da recorrência
`POST_DUE_DATE_ATTEMPT_NOT_ALLOWED`	Tentativa realizada fora da janela permitida após o vencimento
`RECEIVED_TOO_EARLY`	Solicitação enviada com antecedência superior à permitida
`RECEIVED_TOO_LATE`	Solicitação enviada com antecedência inferior à permitida
`OTHER`	Motivo não especificado pela instituição
`OUT_OF_TIME_FRAME_FOR_RETRY`	A cobrança está fora da janela permitida para uma nova tentativa
`INVALID_RECURRING_PAYMENT_ID`	Identificador da recorrência inexistente ou inválido
`RECURRING_PAYMENT_NOT_CONFIRMED`	A recorrência não foi confirmada pelo pagador
`PAYMENT_ALREADY_SCHEDULED`	Já existe uma solicitação de liquidação pendente para a cobrança
`PAYMENT_ALREADY_DONE`	A cobrança já foi liquidada
`PAYMENT_INSTRUCTION_WITHOUT_AUTHORIZATION`	A instrução não possui uma autorização válida associada
`EXCEEDED_MAXIMUM_RETRY_ATTEMPTS`	Quantidade máxima de retentativas excedida
`PARTICIPANT_ISPB_INVALID`	ISPB da instituição financeira inválido ou inexistente
`INVALID_CUSTOMER_CPF_CNPJ`	CPF/CNPJ inválido
`INCORRECT_CUSTOMER_CPF_CNPJ`	CPF/CNPJ incorreto

Como tratar a recusa

Utilize refusalReason para direcionar o comportamento da aplicação.

Cenário	Tratamento
Cobrança já paga ou agendada	Não crie uma nova instrução sem confirmar o estado atual da cobrança
Autorização inválida ou não confirmada	Verifique a autorização antes de continuar a recorrência
Divergência de dados	Corrija os dados antes de uma nova tentativa
Solicitação fora da janela permitida	Revise a data e as regras de processamento
Falta de saldo ou limite	Verifique se o cenário permite retentativa
Limite de retentativas excedido	Não solicite uma nova retentativa para a mesma cobrança
Erro da instituição financeira	Preserve o motivo retornado e trate o cenário conforme o estado da instrução

Não apresente o enum diretamente ao pagador. Faça o mapeamento para uma mensagem adequada ao contexto da sua aplicação.

Retentativas após uma recusa

Nem toda recusa permite uma nova tentativa.

Quando a cobrança estiver elegível para retentativa, siga as regras específicas do Pix Automático.

⚠️
Atenção
As retentativas extradia exigem que a autorização tenha sido criada com a política de retentativa correspondente.
Consulte as regras antes de solicitar uma nova tentativa.

Consulte o processo de retentativas do Pix Automático.

Acompanhe o resultado

Utilize os Webhooks para acompanhar o ciclo da instrução e identificar alterações posteriores à recusa.

Para entender a sequência dos eventos, consulte Fluxos de Webhook do Pix Automático.

Para consultar os payloads e eventos disponíveis, acesse Eventos para Pix Automático.

Próximos passos

Updated 4 days ago

Did this page help you?