Estorno de um Pedido

Este endpoint permite realizar o estorno total ou parcial de uma cobrança (charge) já processada. O estorno é sempre feito no nível da cobrança, e não diretamente no pedido (order).

📌 Um pedido pode possuir uma ou mais cobranças, portanto o estorno deve ser executado para cada charge elegível.

---

Endpoint

PATCH /v2/charges/partial-refund/{uuid} https://api.barte.com/v2/charges/partial-refund/{uuid}

---

Headers

X-Token-Api: YOUR_API_KEY
Content-Type: application/json
Accept: */*

---

Path Param

uuid (obrigatório)

Identificador único da cobrança (charge.uuid).

📌 Esse uuid é obtido:

• Na criação do pedido
• Na consulta do pedido (GET /v2/orders/{uuid})
• Via webhook de atualização de status

---

Body

{
  "value": 100
}

value

Indica o valor que deverá ser estornado da cobrança.

_{📌 Também é possível passar o valor total da cobrança, realizando assim um estorno total.}

---

Exemplo de resposta

[{
  "uuid": "",
  "originalValue": 100,
  "value": 0,
  "refundValue": 100,
  "refundStatus": "processing"
}]

---

Campos mais importantes da resposta

• uuid - Identificador único da cobrança estornada. Use para:

  • Auditoria
  • Suporte
  • Conciliação financeira
• value - Valor atual da cobrança após a solicitação de estorno
• originalValue - Valor original da cobrança
• refundValue - Valor da solicitação de estorno
• refundStatus - Status em que se encontra a solicitação de estorno

---

Fluxo recomendado de estorno

Consultar pedido
      ↓
Identificar charge elegível
      ↓
Executar PATCH /partial-refund
      ↓
Validar retorno
      ↓
Atualizar estado final

---

Boas práticas

• Sempre valide:

  • value
  • originalValue
• Armazene:

  • uuid da charge
  • Status anterior e posterior

---

O que não fazer

• Tentar estornar novamente quando value = 0
• Estornar pedido sem identificar a cobrança correta
• Implementar loop automático de retry sem validação