> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Devolver um cash-in (Refund-in)

> Como solicitar devolução de um recebimento Pix: regras de negócio, prazo de 89 dias, devoluções parciais e auditoria.

## Visão geral

O **refund-in** é a devolução de um recebimento Pix (`cash-in`). Pode ser total ou parcial, com múltiplas devoluções parciais enquanto o saldo disponível permitir.

```mermaid theme={null}
sequenceDiagram
  participant S as Seu sistema
  participant CP as ClearPago
  participant B as BaaS
  participant P as Pagador original

  S->>CP: POST /api/pix/refund-in/{id_do_cash_in}
  CP-->>S: 201 {id do refund, status:PENDING}
  CP->>B: Solicita devolução
  B-->>P: Pix de devolução
  B->>CP: CashInReversal (CONFIRMED)
  CP->>S: Webhook pix_cash_in_reversal
```

## Pré-requisitos

Antes de solicitar a devolução, verifique:

| Condição          | Detalhe                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------- |
| Cash-in em `PAID` | Só é possível devolver recebimentos **confirmados**.                                        |
| Prazo             | Máximo **89 dias** após o recebimento.                                                      |
| Saldo disponível  | A soma das devoluções (pendentes + confirmadas) não pode exceder o valor original recebido. |

## Identificadores críticos

<Warning>
  O path `POST /api/pix/refund-in/{id}` exige o **UUID do cash-in** (campo `id` retornado no `201` de `POST /api/pix/cash-in`). **Não use** o `transactionId` do parceiro BaaS.
</Warning>

## Criar a devolução

```bash theme={null}
curl -X POST https://api.clearpago.com.br/api/pix/refund-in/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <seu_api_token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: req-refund-001" \
  -d '{
    "refundValue": 150.75,
    "reason": "Pedido cancelado pelo cliente",
    "externalId": "estorno-12345"
  }'
```

**Resposta `201`:**

```json theme={null}
{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "status": "PENDING",
  "externalId": "estorno-12345"
}
```

<Warning>
  **Persista o `id` do refund** imediatamente. Ele é necessário para consultar o status com `GET /api/pix/refund/{id}` e para auditoria de devoluções parciais.
</Warning>

### Campos

| Campo         | Obrigatório | Notas                                                                           |
| ------------- | ----------- | ------------------------------------------------------------------------------- |
| `refundValue` | Sim         | Valor em **BRL** a devolver. Pode ser menor que o original (devolução parcial). |
| `reason`      | Não         | Motivo da devolução (descritivo).                                               |
| `externalId`  | Não         | Sua chave de negócio para o estorno. Recomendado para rastreio.                 |

## Devoluções parciais

Você pode fazer múltiplas devoluções parciais sobre o mesmo cash-in, desde que a soma total não ultrapasse o valor original.

**Exemplo:** cash-in de R$ 300,00. Devolução parcial 1: R$ 100,00. Devolução parcial 2: R\$ 200,00.

A plataforma verifica o teto considerando tanto as devoluções `CONFIRMED` quanto as `PENDING`. Se houver devoluções pendentes que somam ao máximo, novas devoluções serão rejeitadas (`422`).

## Monitorar o status

```bash theme={null}
curl https://api.clearpago.com.br/api/pix/refund/d4e5f6a7-b8c9-0123-defa-234567890123 \
  -H "Authorization: Bearer <seu_api_token>"
```

| Status                    | Significado                                            |
| ------------------------- | ------------------------------------------------------ |
| `PENDING`                 | Devolução aceita; aguardando confirmação do BaaS.      |
| `CONFIRMED`               | Devolução **confirmada** — valor devolvido ao pagador. |
| `FAILED`                  | Devolução **rejeitada** pelo BaaS.                     |
| `PROVIDER_RESULT_UNKNOWN` | Resposta ambígua; reconciliação em andamento.          |

## Receber o webhook

```http theme={null}
POST https://seu-sistema.com/webhooks/pix
Content-Type: application/json
Digital-Signature: <base64>

{
  "event_type": "pix_cash_in_reversal",
  "event": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "estorno-12345",
    "status": "CONFIRMED",
    "value_cents": 15075,
    "end_to_end_id": "D07136847202504011500O5222ZRBI5A",
    "fee_amount_cents": 1,
    "confirmed_at": "2026-04-01T15:05:00.000000000Z"
  }
}
```

<Warning>
  **Atenção à semântica de `event.id`:** no evento `pix_cash_in_reversal`, `event.id` é o UUID do **cash-in original**, não o UUID do refund-in. O `event.external_id` é o `externalId` do **refund-in**.
</Warning>

**Chave de idempotência recomendada:** `event_type` + `transaction_id` + `end_to_end_id` do estorno. Evita colisão entre devoluções parciais do mesmo cash-in.

## Erros comuns

| Mensagem                                                   | Causa                   | Ação                                                              |
| ---------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------- |
| `refundValue must be greater than zero`                    | Valor inválido          | Corrija o valor.                                                  |
| `refundValue exceeds the amount available for refund`      | Teto atingido           | Reduza o valor ou verifique devoluções pendentes.                 |
| `refund deadline of 89 days has been exceeded`             | Prazo expirado          | Não é possível devolver; encerre o processo.                      |
| `refunds can only be issued for PAID cash-in transactions` | Cash-in não está `PAID` | Verifique o status com `GET /api/pix/cash-in/{id}`.               |
| `original cash-in transaction not found`                   | UUID inválido           | Verifique se está usando o `id` do cash-in (não `transactionId`). |

## Auditoria

Para listar todos os refunds:

```bash theme={null}
curl "https://api.clearpago.com.br/api/pix/refund?start_date=2026-04-01&end_date=2026-04-30" \
  -H "Authorization: Bearer <seu_api_token>"
```

## Referências

* [POST /api/pix/refund-in/{id}](/api-reference/create-refund-in)
* [GET /api/pix/refund/{id}](/api-reference/get-refund)
* [Referência de eventos de webhook](/webhooks/webhook-event-reference)
* [Modelo de identidade](/core-concepts/identity-model)