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

# Reembolsos

> Entenda como refunds, charges, Payment Intents e transactions se conectam quando um pagamento é devolvido.

Um **reembolso** (`refund`) devolve parte ou todo o valor de uma cobrança já
capturada. Ele é um objeto novo, ligado à [`charge`](/payments/charges) de
origem, com valor, motivo e ciclo de vida próprios.

O reembolso **não apaga nem desfaz o histórico do pagamento**. A cobrança
aconteceu e continua registrada; o refund registra o fato seguinte: o dinheiro
foi devolvido.

<Info>
  **Refund não é cancelamento**

  Cancele quando o dinheiro ainda não foi capturado. Crie um refund quando a
  charge já foi paga e capturada. Um Payment Intent em `requires_capture`, por
  exemplo, deve ser cancelado — ainda não há valor capturado para devolver.
</Info>

## O que muda em cada objeto

Esta é a forma mais segura de entender o fluxo:

| Objeto                                              | O que acontece depois do refund                                                                                                                |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [`payment_intent`](/payments/payment-intents)       | Continua `succeeded`. Esse status registra que o pagamento foi concluído; o refund não transforma esse fato em “não pago”.                     |
| [`charge`](/payments/charges)                       | Continua com `status: "succeeded"` e passa a refletir a devolução em `amount_refunded`, `refunded` e `refunds`.                                |
| `refund`                                            | É criado como um objeto novo e percorre o próprio ciclo: `pending`, `requires_action`, `succeeded`, `failed` ou `canceled`.                    |
| [`transaction`](/api-reference/transactions/object) | Quando o refund é concluído, o extrato recebe um novo lançamento negativo de `type: "refund"`. O valor do lançamento original não é reescrito. |

<Warning>
  Para saber se a devolução terminou, consulte `refund.status`. Nem
  `payment_intent.status` nem `charge.status` substituem o status do refund.
</Warning>

### Reembolso parcial e total na charge

A charge mantém o histórico agregado dos seus refunds:

| Situação                             |         `amount_refunded` | `refunded` | `charge.status` |
| ------------------------------------ | ------------------------: | ---------- | --------------- |
| Nenhum refund                        |                       `0` | `false`    | `succeeded`     |
| Refund parcial de R\$ 50,00          |                    `5000` | `false`    | `succeeded`     |
| Todo o valor capturado foi devolvido | igual a `amount_captured` | `true`     | `succeeded`     |

Uma mesma charge pode ter vários refunds parciais, um de cada vez. Cada
devolução é um objeto independente; devolver R$ 50,00 e depois R$ 100,00 cria
dois refunds, não uma edição do primeiro.

Enquanto uma devolução ainda não terminou, a charge não aceita outra: a criação
responde `409` com `code: "refund_in_progress"`. É isso que garante que a
confirmação de cada estorno seja atribuída à tentativa que a originou. Quando a
tentativa atual chega a `succeeded`, `failed` ou `canceled`, a próxima pode ser
criada sobre o saldo restante.

O valor ainda disponível é:

```text theme={"theme":"css-variables"}
amount_captured
− refunds em pending, requires_action ou succeeded
= valor disponível para um novo refund
```

Refunds que terminam em `failed` ou `canceled` deixam de comprometer esse valor.

## Como o reembolso aparece no extrato

O extrato é aditivo: cada movimento de dinheiro cria uma
[`transaction`](/api-reference/transactions/object). Entradas são positivas e
saídas são negativas, por isso o saldo pode ser calculado pela soma dos
lançamentos sem apagar ou reescrever o passado.

Considere uma venda de R$ 399,00 com R$ 8,74 de taxa:

| Movimento                          | `type`   | `amount` | `fee_amount` | `net_amount` |
| ---------------------------------- | -------- | -------: | -----------: | -----------: |
| Venda original                     | `charge` |  `39900` |        `874` |      `39026` |
| Refund total                       | `refund` | `-39900` |          `0` |     `-39900` |
| Efeito líquido dos dois movimentos | —        |        — |            — |       `-874` |

O lançamento da venda continua com os valores originais. O refund cria o
lançamento de saída, com `source` apontando para o `re_*` que o causou. O
lançamento original pode passar a `status: "refunded"` como uma anotação de
estado, mas `amount`, `fee_amount` e `net_amount` não são reescritos. Como a taxa
da venda original não é devolvida, ela continua sendo um custo de R\$ 8,74 nesse
exemplo.

No objeto refund, `balance_transaction` aponta diretamente para esse novo
lançamento `txn_*` sempre que `status` é `succeeded` — a conclusão da devolução
e o movimento do extrato são gravados na mesma operação, então um nunca existe
sem o outro. Também é possível chegar ao movimento pelo refund que o causou:

```http theme={"theme":"css-variables"}
GET /v1/transactions?source=re_sqUC1414eLnXkw5J
```

## Anatomia do refund

Os campos centrais respondem a quatro perguntas:

| Pergunta                            | Campo                 |
| ----------------------------------- | --------------------- |
| Quanto será devolvido?              | `amount`, em centavos |
| Qual cobrança originou a devolução? | `charge`              |
| Qual pagamento originou a cobrança? | `payment_intent`      |
| A devolução terminou?               | `status`              |

Outros campos ajudam na conciliação:

| Campo                 | Descrição                                                                   |
| --------------------- | --------------------------------------------------------------------------- |
| `balance_transaction` | Movimento negativo do extrato. Sempre presente quando `status = succeeded`. |
| `customer`            | Customer relacionado à charge, quando houver.                               |
| `reason`              | `duplicate`, `fraudulent`, `requested_by_customer` ou `null`.               |
| `failure_reason`      | Motivo normalizado quando `status = failed`.                                |
| `pending_reason`      | Motivo pelo qual o refund ainda está pendente.                              |
| `metadata`            | Pares chave-valor livres para correlacionar com o seu sistema.              |

Veja todos os campos em [Objeto refund](/api-reference/refunds/object).

## Criar um refund

Use `POST /v1/refunds` com **exatamente uma** referência:

* `payment_intent`: a Chargefy encontra a charge capturada correspondente;
* `charge`: você escolhe diretamente qual tentativa será reembolsada.

O campo `amount` é opcional:

* sem `amount`, devolve todo o valor ainda disponível;
* com `amount`, cria um refund parcial nesse valor, sempre em centavos.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/refunds" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-8f4c2a" \
  -d '{
    "amount": 5000,
    "payment_intent": "pi_Qep7Ad2qZFWXph16",
    "reason": "requested_by_customer"
  }'
```

<Tip>
  Reutilize a mesma `Idempotency-Key` ao repetir a mesma operação depois de um
  timeout. Uma nova chave representa uma nova tentativa de criar um refund.
</Tip>

<Warning>
  Um refund concluído é irreversível. Para devolver outro valor da mesma charge,
  crie um novo refund parcial enquanto ainda houver saldo disponível.
</Warning>

O contrato completo, as quatro combinações de criação e os erros possíveis
estão em [Criar um reembolso](/api-reference/refunds/create).

## Ciclo de vida

A resposta do `POST /v1/refunds` pode ser final ou provisória. O refund tem seu
próprio status:

| Status            | Significado                                         | O que fazer                                          |
| ----------------- | --------------------------------------------------- | ---------------------------------------------------- |
| `pending`         | A devolução foi registrada e está sendo processada. | Aguarde atualização.                                 |
| `requires_action` | É necessária uma ação adicional.                    | Leia `next_action` e mantenha o refund em andamento. |
| `succeeded`       | O valor foi devolvido com sucesso.                  | Marque a devolução como concluída.                   |
| `failed`          | A devolução não foi concluída.                      | Leia `failure_reason` e trate a falha.               |
| `canceled`        | O refund foi encerrado antes de concluir.           | Não trate o dinheiro como devolvido.                 |

Somente `succeeded` confirma a devolução. `refund.created` confirma a criação do
objeto, não necessariamente a conclusão financeira.

## Webhooks

Use webhooks para acompanhar mudanças sem fazer polling:

| Evento                | Quando usar                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| `refund.created`      | Registre o refund e o seu estado inicial.                                |
| `refund.updated`      | Atualize o estado local; `data.previous_attributes` informa o que mudou. |
| `refund.failed`       | Trate uma falha de devolução.                                            |
| `charge.refunded`     | Reconcilie a charge depois que uma devolução for concluída.              |
| `transaction.created` | Registre o novo movimento negativo do extrato.                           |

O `data.object` dos eventos `refund.*` tem o mesmo formato retornado por
`GET /v1/refunds/{id}`.

## Operações disponíveis

Refund é um recurso financeiro auditável. Você não remove nem altera seus
valores depois da criação; apenas a `metadata` pode ser atualizada.

| Operação           | Verbo  | URL                |
| ------------------ | ------ | ------------------ |
| Criar              | `POST` | `/v1/refunds`      |
| Consultar          | `GET`  | `/v1/refunds/{id}` |
| Listar             | `GET`  | `/v1/refunds`      |
| Atualizar metadata | `POST` | `/v1/refunds/{id}` |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Objeto refund" icon="rotate-left" href="/api-reference/refunds/object">
    Campos, estados e referências do objeto completo.
  </Card>

  <Card title="Criar um refund" icon="code" href="/api-reference/refunds/create">
    Payloads de criação, idempotência, resposta e erros.
  </Card>

  <Card title="Transactions" icon="list" href="/api-reference/transactions/object">
    Como entradas, taxas e refunds aparecem no extrato.
  </Card>

  <Card title="Devolver um pagamento" icon="arrow-rotate-left" href="/payments/refund-payment">
    Guia de implementação passo a passo.
  </Card>
</CardGroup>