Guia de Estornos

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

Este endpoint permite estornar um parcelamento pago via cartão de crédito, desde que ele esteja recebido ou confirmado.

Ao realizar o estorno, o saldo correspondente será debitado da conta Asaas responsável pelo recebimento, e a cobrança será cancelada no cartão do cliente. O cancelamento pode levar até 10 dias úteis para aparecer na fatura do pagador, pois esse prazo depende do processamento da operadora do cartão.

Quando utilizar este endpoint

Utilize este endpoint quando sua integração precisar:

• cancelar total ou parcialmente um parcelamento pago por cartão de crédito;
• devolver ao cliente o valor de uma compra parcelada;
• estornar apenas uma parte do valor do parcelamento;
• estornar valores vinculados a splits, quando o parcelamento possuir divisão de recebimento;
• corrigir uma cobrança parcelada criada ou paga com valor incorreto.

Para estornar uma cobrança avulsa, utilize o endpoint específico de estorno de cobrança. Este endpoint deve ser usado apenas quando a cobrança estiver vinculada a um parcelamento.

Estorno integral ou parcial

O comportamento do estorno depende dos campos enviados no corpo da requisição:

• Para estornar o valor integral do parcelamento, não informe os campos value nem splitRefunds.
• Para estornar apenas parte do parcelamento, informe o campo value com o valor desejado.
• Para estornar valores específicos de splits, informe o array splitRefunds.
• Para combinar estorno de split com estorno da cobrança principal, informe value e splitRefunds na mesma requisição.

Exemplos de requisição

Estornar o valor integral do parcelamento

Para realizar um estorno integral, envie a requisição sem corpo ou com o corpo vazio.

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/installments/{id}/refund \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --header 'content-type: application/json' \
  --data '{}'

Estornar um valor parcial

Neste exemplo, será estornado apenas R$ 50,00 do parcelamento.

{
  "value": 50.00
}

Estornar valores específicos de splits

Neste exemplo, o estorno será feito apenas sobre os splits informados.

{
  "splitRefunds": [
    {
      "id": "6fba235c-3726-4e32-b4e6-85f46e10cc2e",
      "value": 25.00
    },
    {
      "id": "cff860dd-148e-48ca-ac8e-849684175158",
      "value": 10.00
    }
  ]
}

Combinar estorno de split com estorno da cobrança principal

Neste exemplo, o valor total do estorno será R$ 100,00. Desse total, R$ 40,00 serão estornados de um split, e os R$ 60,00 restantes serão deduzidos da cobrança principal.

{
  "value": 100.00,
  "splitRefunds": [
    {
      "id": "6fba235c-3726-4e32-b4e6-85f46e10cc2e",
      "value": 40.00
    }
  ]
}

Exemplo de resposta

Em caso de sucesso, a resposta retorna os dados atualizados do parcelamento, incluindo as informações de estorno.

{
  "object": "installment",
  "id": "2765d086-c7c5-5cca-898a-4262d212587c",
  "value": 360.00,
  "paymentValue": 30.00,
  "installmentCount": 12,
  "billingType": "CREDIT_CARD",
  "refunds": [
    {
      "status": "DONE",
      "value": 100.00,
      "description": null,
      "refundedSplits": [
        {
          "id": "6fba235c-3726-4e32-b4e6-85f46e10cc2e",
          "value": 40.00,
          "done": true
        }
      ]
    }
  ]
}

Boas práticas de integração

Antes de solicitar o estorno, valide se o parcelamento realmente está apto para estorno e se o valor informado não ultrapassa o valor disponível para devolução.

Em estornos parciais, armazene no seu sistema o valor já estornado para evitar tentativas duplicadas ou valores superiores ao permitido.

Quando utilizar splitRefunds, valide se os IDs informados correspondem aos splits vinculados ao parcelamento. Cada item do array deve informar o identificador do split e o valor que será estornado dele.

Caso a requisição retorne erro 400, revise os valores enviados, o status do parcelamento e os dados de split informados. Para erros 401, valide a chave de API utilizada. Para erros 404, confirme se o identificador do parcelamento está correto.

Evite realizar retries automáticos sem validação do resultado anterior. Antes de tentar novamente, consulte o parcelamento para confirmar se o estorno foi registrado, especialmente em cenários de timeout ou instabilidade de rede.

Impactos do estorno

Após o estorno ser processado:

• o valor correspondente será debitado da conta Asaas;
• o cancelamento será solicitado à operadora do cartão;
• o prazo para o cliente visualizar o cancelamento na fatura pode levar até 10 dias úteis;
• em estornos com split, os valores informados em splitRefunds serão estornados dos respectivos splits;
• se o estorno for parcial, o parcelamento poderá manter histórico de valores pagos e estornados.