Estorno parcial

Como devolver parte de uma venda, a conta que o vendedor vê depois e o webhook que chega em seguida.

O comprador levou dois itens e devolveu um. Você precisa mandar de volta parte da venda, e não ela inteira.

Os valores aqui são inteiros em centavos: R$ 100,00 se envia como 10000. Decimais são recusados com 422, e o porquê está em Valores em centavos.

O pedido

cURL

curl -X POST https://api.usevext.com/v1/charges/ch_01k1y6r6m6q2x0p3d9v4t7c8n2/refund \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: estorno-pedido-1042-item-2" \
  -H "Content-Type: application/json" \
  -d '{"amount": 4000, "reason": "Devolução de um item"}'

Envie amount sempre que o estorno for parcial. Sem ele, devolvemos todo o saldo estornável da cobrança — numa venda de R$ 100,00 intacta, isso são R$ 100,00, e não os R$ 40,00 que você queria.

A conta

201 Created

{
  "object": "refund",
  "id": "rf_01k1y7c3n8b5w2q9r4t6y8u1i3",
  "charge": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
  "status": "succeeded",
  "amount": 4000,
  "currency": "BRL",
  "fee_returned": 280,
  "seller_debit": 3720,
  "reason": "Devolução de um item",
  "failed_reason": null,
  "created_at": "2026-08-05T10:12:00+00:00",
  "processed_at": "2026-08-05T10:12:02+00:00"
}

O comprador recebe amount — R$ 40,00. Do saldo do vendedor saem seller_debit — R$ 37,20. A diferença, R$ 2,80, é a parte da nossa taxa que devolvemos, em fee_returned.

Sempre amount = seller_debit + fee_returned. É a igualdade que responde a pergunta “por que saíram R$ 37,20 se eu estornei R$ 40,00?” antes de ela virar chamado.

O que muda na cobrança

Depois deste estorno, a cobrança fica assim:

Campo	Antes	Depois
status	paid	partially_refunded
refunded_amount	0	4000
refunded_at	null	2026-08-05T10:12:02+00:00

partially_refunded é estado próprio, e não um refunded com asterisco. Tratar esta venda como estornada faria o seu relatório descontar os R$ 100,00 inteiros, quando só R$ 40,00 voltaram.

Ainda cabem R$ 60,00 de estorno (amount - refunded_amount). Pedir mais que isso devolve 422 exceeds_remaining. Um segundo estorno de R$ 60,00 leva a cobrança para refunded.

O webhook que chega depois

charge.refunded traz a cobrança e o estorno, porque as duas perguntas aparecem juntas do outro lado: quanto voltou, e se sobrou algo.

charge.refunded

{
  "id": "evt_01k1y7c4a1b2c3d4e5f6g7h8i9",
  "type": "charge.refunded",
  "created_at": "2026-08-05T10:12:03+00:00",
  "data": {
    "charge": { "status": "partially_refunded", "amount": 10000, "refunded_amount": 4000 },
    "refund": { "amount": 4000, "fee_returned": 280, "seller_debit": 3720 }
  }
}

Ele chega também quando o estorno é feito por nós ou pelo provedor, fora do seu fluxo — então trate o evento mesmo que a sua aplicação nunca chame a API de estorno.

Se o saldo não cobrir

O estorno acontece de qualquer forma. O dinheiro é do comprador e precisa voltar; se o vendedor já sacou, o saldo dele fica negativo, as vendas seguintes cobrem automaticamente, e só o saque fica bloqueado até lá. Ver Saldo do vendedor.

Veja também

Estornos

Todas as regras, incluindo o prazo de 90 dias.

charge.refunded

O evento completo, campo a campo.

---

Ficou algo de fora? Escreva para [e-mail]. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.