Estorno Total de um Pedido

Este endpoint permite realizar o estorno total 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/{uuid}/refund https://api.barte.com/v2/charges/{uuid}/refund

---

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

{
  "asFraud": true
}

asFraud (opcional)

Indica se o estorno está sendo realizado por suspeita de fraude.

📌 Impacta regras internas de risco, antifraude e relatórios.

---

Exemplo de resposta

{
  "uuid": "5df05ef4-2c66-4984-a760-ead83024e811",
  "title": "Teste",
  "expirationDate": "2025-09-20",
  "paidDate": "2025-09-20",
  "value": 100,
  "paymentMethod": "CREDIT_CARD_EARLY_SELLER",
  "status": "REFUND",
  "customer": {
    "uuid": "",
    "document": "001052647",
    "type": "SSN",
    "name": "Joshua Henry",
    "email": "[email protected]",
    "phone": "9409822523",
    "alternativeEmail": ""
  },
  "authorizationCode": null,
  "authorizationNsu": "147163",
  "retryable": false
}

---

Campos mais importantes da resposta

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

  • Auditoria

  • Suporte

  • Conciliação financeira

• status - Status atual da cobrança após a tentativa de estorno. Valores comuns:

  • REFUND → estorno realizado com sucesso

  • PAID → estorno falhou ou não foi processado

  • FAILED → falha definitiva (dependendo do meio de pagamento)

⚠️ Nunca assuma sucesso apenas pela chamada HTTP. Sempre valide o status retornado.

• retryable ⚠️ CAMPO CRÍTICO

  • Indica se é permitido tentar estornar novamente essa cobrança.

  • Comportamento esperado:

    • retryable = true: O estorno falhou, mas é permitido tentar novamente

    • retryable = false: Não é permitido tentar novamente, independentemente do status

📌 Importante: Mesmo que o status não seja REFUND, se retryable = false, novas tentativas são proibidas.

---

Comportamento em caso de falha de estorno

Quando o estorno falha:

• O status da cobrança permanece como estava, sem mudar para REFUND

• O campo retryable define se uma nova tentativa é possível

Exemplo de cenário

Charge status: PAID
Tentativa de estorno → falha
Resposta:
status: PAID
retryable: true

➡ É permitido tentar novamente.

---

Charge status: PAID
Tentativa de estorno → falha definitiva
Resposta:
status: PAID
retryable: false

❌ Não é permitido tentar novamente, mesmo sem status REFUND.

---

Webhooks e estorno

Após uma tentativa de estorno:

• O status da cobrança é atualizado

• Um webhook é disparado para o seu sistema

📌 Sempre:

• Escute o webhook

• Atualize seu estado interno

• Trate divergências como exceção crítica

---

Fluxo recomendado de estorno

Consultar pedido
      ↓
Identificar charge elegível
      ↓
Executar PATCH /refund
      ↓
Validar status + retryable
      ↓
Aguardar webhook
      ↓
Atualizar estado final

---

Boas práticas

• Sempre valide:

  • status

  • retryable

• Armazene:

  • uuid da charge

  • Status anterior e posterior

• Use webhook como confirmação final

• Trate estorno como operação assíncrona

• Diferencie estorno por fraude (asFraud = true) de estorno operacional

---

O que não fazer

• Tentar estornar novamente quando retryable = false

• Estornar pedido sem identificar a cobrança correta

• Ignorar webhook após estorno

• Implementar loop automático de retry sem validação