Estorno Parcial de um Pedido

Este endpoint permite realizar o estorno 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