O que mudou

Um PIX recém-pago fica um tempo pago, mas ainda não conciliado/liquidado pelo provedor. Nesse intervalo o dinheiro ainda não caiu na conta, então não há o que devolver — e uma tentativa de estorno é recusada.

Antes, POST /api/v1/charges/{uuid}/refund repassava a recusa crua do provedor ("Transação inválida para estorno.") como um 400 genérico, sem dizer se valia a pena tentar de novo. Agora esse caso específico vira um sinal claro e programável:

• HTTP 409 (conflito com o estado atual da cobrança).
• Campo code: "pix_not_settled" no corpo da resposta — estável, para você tratar em código sem depender do texto.
• Mensagem acionável: "Este Pix ainda não está disponível para estorno — normalmente porque o pagamento ainda não foi conciliado/liquidado pelo provedor. Tente novamente após a liquidação."

{
  "statusCode": 409,
  "code": "pix_not_settled",
  "message": "Este Pix ainda não está disponível para estorno — normalmente porque o pagamento ainda não foi conciliado/liquidado pelo provedor. Tente novamente após a liquidação.",
  "path": "/api/v1/charges/{uuid}/refund"
}

É um estado temporário e reenviável: repita o estorno depois que o PIX liquidar e ele será processado normalmente.

Precisa fazer algo?

Se o seu código trata falhas de estorno olhando só o status 400, passe a reconhecer também o 409 com code: "pix_not_settled" como "tentar de novo mais tarde". Estornos de cartão e boleto não mudam. O campo code é aditivo — respostas de erro que não têm código continuam idênticas.