# Reembolsar uma venda

URL: https://staging.pagpolar.com/docs/referencia/reembolsos/create-refund

> Reembolsa uma venda sua. Como quem pede é o próprio vendedor, o pedido **já nasce aceito**:
o estorno é enviado ao gateway na hora, a assinatura da venda é cancelada e os acessos do
comprador são revogados. **Não há como desfazer.**

O reembolso é sempre **total**. Reembolso de alguns itens continua só no painel.

A venda precisa estar paga ou já com um pedido de reembolso aberto; em qualquer outra
situação a resposta é `409`. Só existe um pedido em andamento por venda.

A resposta traz a situação do pedido: `REFUNDING` enquanto o gateway não confirma e
`FAILED` quando ele recusa o estorno (por exemplo, por falta de saldo de um co-produtor).
A confirmação vem depois pelo webhook `TRANSACTION_REFUNDED`.

O header `Idempotency-Key` é **obrigatório**: reenviar a mesma chave devolve a resposta
original, sem pedir um segundo estorno.

`POST /refunds`

## Autenticação

- Token Bearer no header `Authorization` (esquema `BearerAuth`). Token de acesso devolvido por POST /auth/token. Envie como "Authorization: Bearer <token>". Vale 24 horas.

## Parâmetros de header

| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `Idempotency-Key` | texto | sim | Exemplo: `2f1c4d2e-8f4a-4c1e-9f7b-6a2d1e3c5b90`. |

## Corpo da requisição

Content-type: `application/json`.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `sale_identifier` | texto | sim | Código público da venda a reembolsar — o `identifier` que vem em `GET /sales`, na resposta da cobrança e no payload dos webhooks. São só dígitos; o prefixo e a URL do checkout que contenha o código também são aceitos. **Não** é o `id` (uuid) da venda: com o uuid a resposta é `404`. A venda precisa ser da própria conta da credencial. Exemplo: `PPO9876543210`. |
| `requested_by` | enum | não | Quem pediu o reembolso, para o registro ficar fiel: `SELLER` quando a decisão foi sua e `CLIENT` quando o comprador pediu por fora (e-mail, telefone, atendimento). O campo só muda o registro, que volta em `requested_by` na consulta — o estorno é imediato nos dois casos, porque quem chama a rota é o vendedor. Valores: `SELLER`, `CLIENT`. Exemplo: `SELLER`. |
| `reason` | texto | não | Motivo do reembolso, em texto livre. Fica gravado no pedido e aparece em `GET /refunds`. Exemplo: `Cliente desistiu da compra`. |
| `customer_observation` | texto | não | Observação do comprador, quando houver. Exemplo: `Pediu o cancelamento por e-mail`. |

### Exemplo do corpo

Reembolso total:

```json
{
  "sale_identifier": "PPO9876543210",
  "reason": "Cliente desistiu da compra"
}
```

## Respostas

### 201 — Reembolso solicitado

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `data` | [Reembolso](/docs/referencia/entidades/reembolso) | não | — |

## Erros

| Status | Descrição |
| --- | --- |
| `400` | Dados inválidos, Idempotency-Key ausente, ou já existe um pedido de reembolso em andamento para a venda |
| `401` | Token ausente, inválido ou expirado, ou credencial revogada ou expirada. Chame POST /auth/token para obter um token novo. |
| `403` | IP não autorizado |
| `404` | Venda não encontrada |
| `409` | A venda não está paga, não é possível reembolsar |
| `429` | Limite de requisições excedido |
| `503` | Serviço de limite indisponível — repita a requisição com a mesma Idempotency-Key |

Lista completa de códigos e como tratá-los: [Erros](/docs/guias/fundamentos/erros).