# Devoluções de PIX

Como devolver um PIX recebido pela API da SinapsePay, total ou parcialmente, em até 90 dias, e acompanhar a devolução até o banco concluir.

```http
POST /v1/cobrancas/{id}/devolver
```

Escopo `cobrancas:devolver`. Devolve ao pagador um PIX recebido, no todo ou em parte.

| Campo | Tipo | |
|---|---|---|
| `valor` | inteiro | Em centavos. Vazio: devolve o que resta do pagamento |
| `endToEndId` | texto | O pagamento a devolver. Vazio: o único pagamento da cobrança com valor a devolver |
| `motivo` | texto | Até 140 caracteres; vai para o pagador |

```json
{ "valor": 500, "motivo": "Produto em falta no pedido" }
```

A resposta é `202` com a cobrança e a devolução em `devolucoes`, como `solicitada`. O banco conclui em seguida:

| `status` | |
|---|---|
| `solicitada` | Na fila para o banco |
| `em_processamento` | O banco aceitou e está concluindo |
| `devolvida` | Dinheiro devolvido; `idDevolucao` é o identificador no Banco Central |
| `nao_realizada` | O banco recusou; veja `motivoFalha` |

## Regras

- Só **PIX pago pelo banco** (baixas manuais não entram) e só até **90 dias** do pagamento (regra do Banco Central): depois, `409 REFUND_EXPIRED`.
- A soma das devoluções **nunca passa do valor pago**. Pedir mais: `422`, com quanto resta.
- Devolvida por inteiro, a cobrança vira `devolvida`; em parte, continua `paga` com a lista de devoluções.
- Cada devolução é pedida ao banco uma única vez, mesmo se você repetir a chamada (use a [`Idempotency-Key`](/docs/idempotencia)) ou se a comunicação cair no meio.

Quando a devolução termina, o seu sistema recebe `cobranca.devolvida` ou `cobranca.devolucao_recusada` nos [avisos](/docs/avisos).