Estornos

Como interpretar o atributo refunds retornado em cobranças com estornos.

Use o atributo refunds para identificar e conciliar estornos vinculados a uma cobrança.

Quando uma cobrança possui um ou mais estornos, o objeto da cobrança retorna o array refunds. Cada item representa uma tentativa ou conclusão de estorno e deve ser usado pela sua integração para atualizar o status financeiro do pedido, exibir comprovantes ao cliente e conciliar valores devolvidos.

Exemplo de retorno

O exemplo abaixo mostra o campo refunds dentro de um objeto JSON válido:

{
  "refunds": [
    {
      "dateCreated": "2022-02-21 10:28:40",
      "status": "DONE",
      "value": 2.00,
      "description": "Pagamento a mais",
      "endToEndIdentifier": null,
      "transactionReceiptUrl": "https://www.asaas.com/comprovantes/6677732109104548",
      "refundedSplits": [
        {
          "id": "cff860dd-148e-48ca-ac8e-849684175158",
          "value": 10,
          "done": true
        }
      ]
    }
  ]
}

Campos do estorno

Campo	Tipo	Descrição
`dateCreated`	string	Data e hora em que o estorno foi criado.
`status`	string	Situação atual do estorno. Os valores possíveis são `PENDING`, `CANCELLED` e `DONE`.
`value`	number	Valor estornado na cobrança.
`description`	string	Descrição informada para identificar o motivo do estorno.
`endToEndIdentifier`	string ou `null`	Identificador de rastreio da transação, quando disponível. Trate `null` como ausência temporária ou indisponibilidade do identificador.
`transactionReceiptUrl`	string ou `null`	URL do comprovante do estorno, quando disponível. Exiba ou armazene esse link somente após confirmar que ele foi retornado.
`refundedSplits`	array	Lista de splits relacionados ao estorno, quando a cobrança possuir divisão de valores.

Status do estorno

Os status disponíveis no retorno do campo refunds são:

PENDING: o estorno foi solicitado, mas ainda não foi concluído. Mantenha o pedido como aguardando confirmação de estorno na sua integração.
CANCELLED: o estorno foi cancelado e não deve ser tratado como valor devolvido.
DONE: o estorno foi concluído. Use esse status para confirmar a devolução do valor ao cliente e atualizar sua conciliação.

Comportamentos e cuidados

Uma cobrança pode retornar mais de um item em refunds. Percorra todo o array antes de calcular o valor total estornado.
Não use apenas a existência do array refunds para considerar o estorno concluído. Confirme se o item possui status igual a DONE.
Campos como endToEndIdentifier e transactionReceiptUrl podem retornar null ou ficar indisponíveis até a conclusão do processo. Prepare sua integração para tratar esses campos como opcionais.
Quando refundedSplits for retornado, use os campos value e done de cada split para acompanhar a devolução dos valores divididos.
Para conciliação, registre o value, o status, a dateCreated e a transactionReceiptUrl quando disponível.