# Criar devolução PIX
`POST /v1/wallet/refunds`
**Área:** Devolução Pix

**Scopes necessários:** `wallet/write`

Cria uma **devolução PIX** a partir do `endToEndId` da transação original. A devolução pode ser parcial ou total.

> ⚠️ **Atenção:** o campo `reason` (motivo da devolução) é **obrigatório**.

Valores aceitos para `reason`:

- `CUSTOMER_REQUEST` — solicitação do cliente
- `FRAUD` — suspeita de fraude
- `BANK_ERROR` — erro bancário
- `PIX_CHANGE_ERROR` — erro na transação

A devolução nasce em geral como `PROCESSING`. Guarde o `refundId` retornado e acompanhe a confirmação pela rota **Consultar status da devolução PIX** (`GET /v1/wallet/refunds`).

### Request body

```json
{
  "accountId": "459013777",
  "endToEndId": "E003603052026032511186a4f4cdf139",
  "amount": 1.00,
  "reason": "CUSTOMER_REQUEST",
  "chargeId": "cha_1774437468463_4hj927ips"
}
```

### Campos do body

**Obrigatórios:** `endToEndId`, `amount`, `reason`

| Campo | Descrição |
|---|---|
| `endToEndId` | EndToEndId da transação PIX original. |
| `amount` | Valor da devolução (parcial ou total). |
| `reason` | Um de: BANK_ERROR, FRAUD, CUSTOMER_REQUEST, PIX_CHANGE_ERROR. |

**Opcionais**

| Campo | Descrição |
|---|---|
| `accountId` | Número da subconta. Se omitido, opera na conta principal. |
| `chargeId` | ID da charge associada. |

### Resposta 201 — Sucesso

```json
{
    "refundId": "ref_1774437918293_jm2hen5y7",
    "status": "PROCESSING",
    "amount": 1,
    "reason": "CUSTOMER_REQUEST",
    "endToEndId": "E003603052026032511186a4f4cdf139",
    "returnIdentification": "D13935893202603251125zbRSLI3lqPH",
    "chargeId": "cha_1774437468463_4hj927ips",
    "createdAt": "2026-03-25T11:25:18.293Z"
}
```

### Resposta 401 — Não autorizado

```json
{
    "error": {
        "message": "Subconta nao pertence a esta conta",
        "code": "OWNERSHIP_MISMATCH",
        "details": null,
        "timestamp": "2026-03-25T11:28:25.397Z"
    }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/post-criar-devolucao-pix
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json