Guia de Estornos

Confira o guia de estornos para mais informações.

POST /v3/payments/{id}/bankSlip/refund

Endpoint responsável por iniciar a solicitação de estorno de uma cobrança paga por boleto.

Diferente de estornos realizados em meios de pagamento que permitem devolução direta para a origem do pagamento, o estorno de boleto exige que o cliente pagador informe os dados bancários da conta em que deseja receber o valor. Por isso, ao solicitar o estorno, a API retorna um link que deve ser enviado ao cliente para preenchimento dos dados bancários e envio dos documentos de identificação.

Esse fluxo permite que o Asaas valide as informações necessárias antes de concluir a devolução do valor.

Quando utilizar

Utilize este endpoint quando sua integração precisar solicitar a devolução de uma cobrança paga por boleto.

Alguns cenários comuns incluem:

• cancelamento de uma venda paga por boleto;
• desistência da compra após o pagamento;
• cobrança emitida ou paga incorretamente;
• devolução solicitada pelo cliente final;
• necessidade de iniciar o processo de reembolso de um boleto por meio da API.

Este endpoint deve ser utilizado apenas para cobranças pagas por boleto. Para estornos de outros meios de pagamento, utilize o endpoint correspondente ao tipo da cobrança.

Quando não utilizar

Não utilize este endpoint para:

• estornar cobranças pagas por cartão de crédito;
• estornar cobranças Pix;
• cancelar uma cobrança ainda não paga;
• remover uma cobrança;
• alterar dados da cobrança original;
• considerar o valor devolvido imediatamente após a chamada.

Caso a cobrança ainda não tenha sido paga, avalie se o fluxo correto é atualizar, remover ou cancelar a cobrança, conforme o cenário da integração.

Permissão necessária

Para utilizar este endpoint, a chave de API deve possuir permissão para solicitação de estornos:

PAYMENT_REFUND:WRITE

Caso a chave utilizada não possua permissão para essa operação, a requisição poderá retornar erro de autorização.

Fluxo do estorno de boleto

O estorno de boleto depende da participação do cliente pagador para preenchimento dos dados necessários.

Em uma integração típica, o fluxo ocorre da seguinte forma:

Identificar a cobrança paga por boleto
↓
Solicitar o estorno via API
↓
Receber o link de preenchimento retornado pelo Asaas
↓
Enviar o link ao cliente pagador
↓
Cliente informa os dados bancários
↓
Cliente envia os documentos de identificação solicitados
↓
Asaas valida as informações recebidas
↓
Estorno é processado conforme o resultado da análise
↓
Integração acompanha o status do estorno

A chamada para este endpoint não conclui o estorno imediatamente. Ela inicia o processo e retorna o link necessário para que o cliente complete as informações obrigatórias.

Parâmetro da requisição

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

O campo id deve corresponder a uma cobrança existente no Asaas e elegível para estorno de boleto.

Este endpoint não exige envio de parâmetros no corpo da requisição.

Retorno esperado

Ao solicitar o estorno com sucesso, a API retorna as informações necessárias para continuidade do processo, incluindo o link que deverá ser acessado pelo cliente pagador.

Esse link é retornado no campo requestUrl e permite que o cliente:

• informe os dados bancários para recebimento do valor;
• envie documentos de identificação;
• comprove que é titular da conta bancária informada.

Exemplo de chamada

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/payments/pay_123456789/bankSlip/refund \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Exemplo de resposta

Em caso de sucesso, a API retorna o link que deverá ser enviado ao cliente pagador.

{
  "requestUrl": "https://sandbox.asaas.com/solicitar-estorno/37ij5mdxwo1234"
}

Regras de negócio importantes

Antes de solicitar o estorno de boleto, considere as seguintes regras:

• a cobrança deve existir no Asaas;
• a cobrança deve ser de boleto;
• a cobrança precisa estar em uma situação compatível com solicitação de estorno;
• a chave de API utilizada deve possuir permissão para estorno;
• o link retornado deve ser preenchido pelo cliente pagador;
• os dados bancários devem ser informados pelo cliente no link disponibilizado;
• os documentos enviados devem comprovar a identidade do cliente e a titularidade da conta bancária informada;
• o estorno não é concluído no momento da chamada, pois depende do envio e validação das informações pelo cliente.

Caso a cobrança não seja elegível para estorno de boleto, a API poderá retornar erro.

Comportamentos relevantes

Ao utilizar este endpoint, considere os seguintes comportamentos:

• a solicitação de estorno inicia um fluxo assíncrono;
• o retorno da API não significa que o valor já foi devolvido ao cliente;
• o cliente precisa preencher o link para que o processo avance;
• documentos inválidos, incompletos ou inconsistentes podem impedir a conclusão do estorno;
• enquanto o estorno não for finalizado, a integração deve acompanhar o status da solicitação;
• a situação final do estorno deve ser considerada apenas após confirmação do processamento.

Os status de estorno podem ser acompanhados pelos recursos de consulta de estornos da cobrança.

Status do estorno

Após a solicitação, o estorno poderá passar por diferentes status.

Os principais status retornados no campo refunds são:

A integração deve estar preparada para acompanhar esses status e atualizar o pedido ou registro interno somente quando houver confirmação compatível com a regra de negócio da operação.

Impactos operacionais

O estorno de boleto pode impactar diretamente a conciliação financeira da integração.

Ao iniciar esse processo, avalie:

• se o pedido deve ser cancelado imediatamente ou apenas após a conclusão do estorno;
• se o status interno da venda deve permanecer como “estorno solicitado” enquanto o cliente não preencher o link;
• se será necessário enviar comunicações adicionais ao cliente;
• se a operação possui fluxos de split, repasse ou controle financeiro interno relacionados à cobrança;
• como sua plataforma irá tratar estornos pendentes, concluídos ou cancelados.

Caso a cobrança esteja vinculada a outros fluxos financeiros, como split de pagamento, considere também os efeitos do estorno nesses recursos.

Erros comuns

Alguns erros comuns ao utilizar este endpoint incluem:

Em caso de erro, valide se o ID da cobrança está correto, se a cobrança é de boleto e se a chave de API possui a permissão necessária.

Boas práticas

Para uma implementação mais segura, recomenda-se:

• armazenar o ID da cobrança no momento da criação;
• validar se a cobrança foi paga antes de solicitar o estorno;
• utilizar este endpoint somente para cobranças de boleto;
• enviar o link retornado para o cliente por um canal seguro;
• orientar o cliente a preencher corretamente os dados bancários;
• acompanhar o status do estorno após a solicitação;
• registrar internamente a data da solicitação e o link retornado;
• não considerar o estorno concluído apenas pela resposta inicial da API;
• consultar os estornos da cobrança para atualizar o status interno da operação.

Cuidados em Sandbox

Este endpoint pode ser utilizado em Sandbox para validação do fluxo de solicitação de estorno.

Durante os testes, recomenda-se validar:

• se a integração consegue solicitar o estorno;
• se o link é retornado corretamente;
• se o sistema interno registra o estorno como pendente;
• se o fluxo de acompanhamento do status está implementado corretamente.

Evite utilizar dados reais de terceiros durante os testes.

Conteúdos relacionados

Consulte também:

• Guia de Estornos;
• Listar estornos de uma cobrança;
• Estornar cobrança;
• Estornar parcelamento;
• Cobranças via boleto;
• Split de Pagamentos, quando aplicável à operação;
• Webhooks para cobranças.