> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Reembolsos
> Como funcionam os reembolsos — de onde eles nascem, o ciclo até o dinheiro voltar e a decisão manual.
O **reembolso** (`rfd_`) devolve ao comprador o valor de um pagamento já liquidado. Ele registra o
pedido, o motivo e o caminho percorrido até o dinheiro sair — no cartão e no Pix pelo próprio
gateway, no boleto por transferência bancária.
Você **não cria um reembolso neste recurso**: não existe `POST /refunds`. Ele nasce do estorno de
uma [transação](/pt-BR/transactions) ou de um [pagamento](/pt-BR/payments/refund), e é lá que o
`reason` é informado. Os endpoints abaixo consultam o que já existe e decidem o que está pendente.
**O reembolso carrega o comprador e o checkout da venda de origem.** `customerId`, `customerName`,
`customerEmail`, `customerDocument` e `customerDocumentType` dizem de quem era a compra, e
`additionalInfo.checkoutLinkId` liga o estorno ao link de checkout que a vendeu — os mesmos campos
em `GET /refunds/:id`, na listagem e em todos os eventos `refund.*`, para você reagir a um estorno
sem consultar a transação. Eles são copiados da transação **no momento em que o reembolso é
criado**: editar o cadastro do cliente depois não os altera. `additionalInfo` é nulo quando a
venda foi criada direto pela API, sem link de checkout; os campos do comprador só são nulos quando
a própria transação não tem cliente.
Todas as rotas exigem o header `x-api-key` (sua chave de sandbox). Veja
[Autenticação](/pt-BR/autenticacao). Os exemplos nas páginas de cada endpoint usam a base URL de
sandbox `https://api.sandbox.z2pay.com/v1`.
***
## Endpoints
Cada endpoint tem sua própria página, com os campos aceitos, exemplos e o playground para testar.
| Método | Rota | Descrição |
| ------ | ---------------------- | ------------------------------------------------------ |
| `GET` | `/refunds` | [Lista reembolsos com filtros](/pt-BR/refunds/list) |
| `GET` | `/refunds/:id` | [Busca um reembolso por ID](/pt-BR/refunds/get) |
| `POST` | `/refunds/:id/approve` | [Aprova um reembolso pendente](/pt-BR/refunds/approve) |
| `POST` | `/refunds/:id/refuse` | [Recusa um reembolso pendente](/pt-BR/refunds/refuse) |
***
## Status do reembolso
O status diz em que ponto do caminho o dinheiro está. Quem determina a maior parte dele é o gateway
(cartão e Pix) ou o andamento da transferência (boleto) — a você cabe apenas a decisão inicial,
quando ela é manual. Os estados terminais são `refunded`, `refused` e `failed`.
| Status | O que significa | Quando acontece |
| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `pending` | Aguardando decisão | Reembolso criado com a aprovação automática desligada, ou reembolso de boleto (que sempre nasce assim) |
| `approved` | Aprovado, a caminho do processamento | Logo após a aprovação, enquanto o pedido segue para o gateway |
| `processing` | Sendo processado no gateway | Cartão ou Pix aprovado, aguardando a confirmação do gateway |
| `refunded` | Concluído — o valor voltou ao comprador | O gateway confirmou o estorno, ou a transferência do boleto foi liquidada |
| `refused` | Pedido recusado | Alguém recusou o reembolso em `POST /refunds/:id/refuse` |
| `failed` | Falha no processamento | O gateway rejeitou o estorno ou houve erro técnico |
| `awaiting_bank_details` | Boleto: aguardando os dados bancários | Reembolso de boleto aprovado — o comprador ainda não informou a conta |
| `bank_details_received` | Boleto: dados recebidos | O comprador informou a conta e a transferência pode ser montada |
| `invalid_bank_details` | Boleto: dados inválidos | A conta informada não passou na validação; um novo pedido é enviado ao comprador |
| `ted_processing` | Boleto: transferência em andamento | O Pix/TED de devolução foi disparado e ainda não liquidou |
### O que decide o status inicial
Um reembolso raramente começa onde se espera: o método de pagamento e uma configuração da sua conta
mudam o ponto de partida. Três regras explicam o que você vai ver.
**Com aprovação automática, cartão e Pix já nascem resolvidos.** A configuração vem habilitada por
padrão: o reembolso é criado, aprovado e processado no gateway dentro da própria requisição de
estorno, e a resposta já traz `refunded` ou `failed`. Os estados `approved` e `processing` existem,
mas são atravessados durante essa chamada — você não os vê numa resposta síncrona.
**Boleto sempre nasce `pending`,** mesmo com a aprovação automática ligada, porque não há estorno
a fazer no gateway: o valor volta por transferência bancária e é preciso saber para qual conta.
Ao ser aprovado, ele vai para `awaiting_bank_details` — não para `processing`.
**A coleta dos dados bancários acontece fora desta API.** O comprador recebe um convite para
informar a conta, e o reembolso caminha sozinho por `bank_details_received` e `ted_processing`
conforme a transferência avança. Não há endpoint aqui para enviar esses dados.
***
## Veja também
Onde o reembolso nasce: o estorno de um pagamento, no todo ou em parte.
O estorno da transação inteira, e como ele afeta o status dela.
A devolução que parte do emissor do cartão, e não de você.
A taxa de reembolso que incide sobre a operação.