Endpoint responsável por remover uma cobrança cadastrada no Asaas.

Essa operação deve ser utilizada quando a cobrança não deve mais permanecer ativa no fluxo da integração, como em casos de emissão incorreta, substituição por uma nova cobrança ou interrupção de uma cobrança que ainda não deve ser disponibilizada para pagamento.

A exclusão remove a cobrança do fluxo ativo, mas não deve ser tratada como estorno, reembolso ou confirmação de devolução de valores já pagos.

Quando utilizar este endpoint

Utilize este endpoint quando sua integração precisar:

• remover uma cobrança criada incorretamente;
• impedir que uma cobrança pendente continue disponível para pagamento;
• limpar cobranças criadas em testes;
• corrigir uma operação antes de gerar uma nova cobrança;
• substituir uma cobrança por outra com dados ajustados;
• remover uma cobrança que não deve mais ser apresentada ao pagador;
• sincronizar a remoção de uma cobrança entre o Asaas e o sistema de origem.

Esse endpoint é mais indicado para cobranças que ainda não foram pagas ou que não devem mais seguir no fluxo de cobrança.

Quando não utilizar

Não utilize este endpoint para:

• devolver valores ao pagador;
• estornar uma cobrança paga;
• cancelar definitivamente uma assinatura;
• remover todas as parcelas de um parcelamento;
• alterar dados de uma cobrança existente;
• corrigir uma cobrança que ainda pode ser atualizada;
• tratar conciliação financeira de pagamentos já recebidos.

Caso a cobrança já tenha sido paga e a intenção seja devolver o valor ao cliente, utilize o fluxo de estorno correspondente ao meio de pagamento.

Caso a cobrança pertença a uma assinatura, parcelamento ou outro recurso de origem, avalie também o comportamento desse recurso antes de remover apenas a cobrança individual.

Parâmetro da requisição

Este endpoint utiliza apenas o identificador da cobrança no path da requisição.

O id deve corresponder a uma cobrança previamente criada no Asaas, normalmente no formato:

pay_pCczZjBBr6RL

Esse identificador é retornado no momento da criação da cobrança e também pode ser obtido na listagem ou consulta de cobranças.

Este endpoint não utiliza parâmetros no body.

Pré-requisitos

Antes de remover uma cobrança, verifique se:

• a cobrança foi criada anteriormente no Asaas;
• sua aplicação possui o id da cobrança;
• a cobrança pertence à conta autenticada;
• a chave de API utilizada pertence à conta correta;
• a cobrança ainda deve ser removida do fluxo ativo;
• o pagador não deve mais utilizar essa cobrança para pagamento;
• sua aplicação está preparada para atualizar o status da cobrança na base interna.

Fluxo recomendado

Em uma integração típica, a exclusão de cobrança deve seguir o fluxo abaixo:

Identificar a cobrança na base interna
↓
Consultar a cobrança no Asaas
↓
Validar se ela ainda deve ser removida
↓
Solicitar a exclusão
↓
Validar a resposta da API
↓
Atualizar o status da cobrança na base interna
↓
Interromper ações relacionadas à cobrança removida

Antes de remover a cobrança, recomenda-se consultar seu estado atual para evitar excluir uma cobrança que já foi paga, substituída, estornada ou vinculada a outro fluxo operacional.

Exemplo de chamada

curl --request DELETE \
  --url https://api-sandbox.asaas.com/v3/payments/pay_pCczZjBBr6RL \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Exemplo de resposta

Em caso de sucesso, a API retorna uma resposta resumida confirmando a exclusão da cobrança.

{
  "deleted": true,
  "id": "pay_pCczZjBBr6RL"
}

Comportamento da exclusão

Ao excluir uma cobrança:

• a cobrança deixa de permanecer ativa no fluxo da integração;
• o identificador original da cobrança é mantido na resposta;
• o link da cobrança não deve continuar sendo enviado ao pagador;
• a cobrança não deve mais ser apresentada como uma cobrança ativa no sistema de origem;
• a operação não cria uma nova cobrança;
• a operação não altera automaticamente outras cobranças;
• a operação não remove automaticamente uma assinatura ou parcelamento de origem;
• a operação não representa devolução de valores pagos;
• a aplicação deve atualizar sua base interna para refletir que a cobrança foi removida.

Dependendo do cenário, uma cobrança removida poderá ser restaurada posteriormente por meio do endpoint específico de restauração.

Exclusão, atualização e estorno

A exclusão de cobrança não deve ser confundida com atualização ou estorno.

Relação com assinaturas e parcelamentos

Uma cobrança pode ter sido criada de forma avulsa ou gerada automaticamente a partir de outro recurso, como assinatura ou parcelamento.

Antes de excluir uma cobrança, verifique se ela está vinculada a:

• uma assinatura;
• um parcelamento;
• um pedido no sistema de origem;
• uma nota fiscal;
• um fluxo de split;
• um controle interno de conciliação;
• notificações ou comunicações enviadas ao pagador.

A exclusão de uma cobrança individual não significa, necessariamente, que o recurso de origem foi encerrado.

Exemplos:

• se a cobrança pertence a uma assinatura, novas cobranças podem continuar sendo geradas conforme a recorrência;
• se a cobrança pertence a um parcelamento, outras parcelas podem permanecer ativas;
• se a cobrança possui nota fiscal ou controle fiscal associado, avalie os impactos antes da remoção;
• se a cobrança está vinculada a um pedido externo, atualize o pedido para evitar divergência entre sistemas.

Restauração de cobrança removida

Caso a exclusão tenha sido realizada por engano, avalie o uso do endpoint de restauração de cobrança removida.

A restauração permite reativar uma cobrança removida anteriormente, utilizando o mesmo identificador original, quando o cenário for compatível.

Fluxo recomendado:

Cobrança removida por engano
↓
Solicitar restauração
↓
Consultar a cobrança restaurada
↓
Atualizar a base interna
↓
Retomar o fluxo operacional

Idempotência e chamadas repetidas

Não trate este endpoint como uma operação idempotente sem validar a resposta da API.

Se a exclusão for solicitada mais de uma vez para a mesma cobrança, o comportamento pode variar conforme o estado atual do registro.

Possíveis cenários:

Após uma exclusão bem-sucedida, atualize sua base interna para evitar novas tentativas desnecessárias.

Regras de negócio importantes

Antes de implementar este endpoint, considere as seguintes regras:

• somente cobranças existentes e pertencentes à conta autenticada podem ser removidas;
• o id informado deve corresponder a uma cobrança criada previamente no Asaas;
• a exclusão remove a cobrança do fluxo ativo;
• a exclusão não representa estorno, reembolso ou devolução de valores;
• cobranças pagas, confirmadas ou vinculadas a fluxos financeiros concluídos podem exigir tratamento específico;
• cobranças vinculadas a assinaturas ou parcelamentos podem ter dependências com o recurso de origem;
• a exclusão não altera automaticamente o status do pedido no sistema externo;
• a exclusão não deve ser usada como mecanismo de conciliação financeira;
• a aplicação deve registrar e sincronizar internamente a remoção.

Erros comuns

Alguns erros comuns ao utilizar este endpoint incluem:

Boas práticas

Ao implementar a exclusão de cobranças, recomenda-se:

• armazenar o id da cobrança retornado pelo Asaas no momento da criação;
• consultar a cobrança antes de excluí-la;
• validar o status atual da cobrança;
• diferenciar exclusão, estorno e atualização;
• evitar excluir cobranças pagas sem avaliar o fluxo financeiro correto;
• registrar logs de quem solicitou a exclusão e quando ela ocorreu;
• atualizar a base interna após a exclusão bem-sucedida;
• interromper envio de links ou notificações relacionadas à cobrança removida;
• validar recursos relacionados, como assinatura, parcelamento, nota fiscal ou pedido externo;
• tratar erros 400, 401 e 404 de forma clara;
• evitar retentativas automáticas sem consultar o estado atual da cobrança;
• testar o fluxo em Sandbox antes de disponibilizar a funcionalidade em Produção.

Impactos operacionais

A exclusão de uma cobrança pode impactar diretamente a operação financeira e a experiência do cliente.

Alguns impactos possíveis são:

• indisponibilidade do link da fatura;
• interrupção da cobrança ao pagador;
• necessidade de atualização do pedido no sistema de origem;
• divergência entre Asaas e sistema externo se a base não for sincronizada;
• risco de duplicidade caso uma nova cobrança seja criada sem remover ou substituir a anterior corretamente;
• impacto em relatórios financeiros internos;
• necessidade de revisar assinaturas, parcelamentos ou notas fiscais vinculadas;
• aumento de contatos com suporte caso o cliente tente pagar uma cobrança removida.

Por isso, trate a exclusão como uma operação sensível e mantenha rastreabilidade interna.

Cuidados em Sandbox

Este endpoint pode ser testado em Sandbox.

Recomenda-se validar os seguintes cenários:

• criar uma cobrança;
• consultar a cobrança criada;
• excluir a cobrança;
• consultar a cobrança após a exclusão;
• tentar excluir novamente a mesma cobrança;
• restaurar a cobrança removida, quando aplicável;
• tentar excluir um ID inexistente;
• validar como sua aplicação atualiza a base interna em cada resposta.

Esses testes ajudam a definir o comportamento esperado antes da operação em Produção.

Conteúdos relacionados

Consulte também:

• Criar nova cobrança;
• Recuperar uma única cobrança;
• Listar cobranças;
• Atualizar cobrança existente;
• Restaurar cobrança removida;
• Estornar cobrança;
• Criar assinatura;
• Remover assinatura;
• Cancelar cobranças de um parcelamento;
• Webhooks;
• O que pode ser testado em Sandbox.