> ## 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.

# Chargebacks

> Como funcionam os chargebacks — a contestação do portador, a janela de defesa e o efeito no seu saldo.

O **chargeback** (`cbk_`) é a contestação que o portador do cartão abre junto ao banco emissor. Quando
a adquirente nos notifica, o caso é criado automaticamente e o pagamento correspondente entra em
contestação. A partir daí você tem uma janela para anexar provas — nota fiscal, comprovante de
entrega, contrato assinado — e defender a cobrança.

Você **não abre nem decide um chargeback pela API**: o caso nasce de um webhook da adquirente, e é
ela quem julga o desfecho. O que a API oferece é acompanhar o andamento e enviar documentos dentro
do prazo.

<Info>
  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`.
</Info>

***

## 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`  | `/chargebacks`                                    | [Lista chargebacks com filtros](/pt-BR/chargebacks/list)                        |
| `GET`  | `/chargebacks/:id`                                | [Busca um chargeback por ID](/pt-BR/chargebacks/get)                            |
| `GET`  | `/chargebacks/:id/documents`                      | [Lista os documentos enviados](/pt-BR/chargebacks/documents)                    |
| `GET`  | `/chargebacks/:id/documents/:documentId/download` | [Gera a URL de download de um documento](/pt-BR/chargebacks/documents-download) |
| `POST` | `/chargebacks/:id/documents`                      | [Envia um documento de contestação](/pt-BR/chargebacks/documents-post)          |

***

## Status do chargeback

Quem move o status é a adquirente, não você: o caso avança em linha reta, sem voltar atrás. Só um dos
estados aceita ação sua — `under_review`, a janela em que as provas são recebidas.

| Status         | O que significa                        | Quando acontece                                                                |
| -------------- | -------------------------------------- | ------------------------------------------------------------------------------ |
| `opened`       | Caso recém-criado                      | A adquirente notificou a contestação e o chargeback foi aberto automaticamente |
| `under_review` | Em análise, janela de defesa aberta    | Logo após a abertura — é aqui, e só aqui, que você envia documentos            |
| `submitted`    | Provas enviadas, aguardando julgamento | O material seguiu para a adquirente e o caso saiu das suas mãos                |
| `won`          | Contestação ganha                      | A adquirente decidiu a seu favor: caso encerrado                               |
| `lost`         | Contestação perdida                    | A adquirente decidiu a favor do portador: caso encerrado                       |

### O que o chargeback faz com o seu dinheiro

O caso não mexe só no status do pagamento — ele movimenta a sua carteira desde a abertura, antes de
qualquer decisão. Três regras explicam os lançamentos que você vai ver.

<Note>
  **O pagamento entra em contestação antes de o caso existir.** A ordem é: a adquirente notifica, o
  pagamento vai para `in_protest` — e é desse evento que o chargeback nasce, já em `opened`. Não há
  um momento com o caso aberto e o pagamento ainda `paid`.
</Note>

<Note>
  **O valor sai assim que a análise começa.** Ao entrar em `under_review`, o valor contestado é
  descontado, junto com a taxa de chargeback — a adquirente retém na abertura da disputa, não no
  desfecho. O dinheiro fica fora do seu saldo enquanto o caso corre.
</Note>

<Note>
  **Ganhar devolve tudo, inclusive a taxa.** Em `won`, o pagamento volta para `paid`, o valor
  retido volta ao seu saldo e a taxa de chargeback é estornada. Em `lost`, o pagamento vai para
  `chargeback` — o principal já tinha saído na abertura, então o que ainda incide é a multa,
  configurável por conta.
</Note>

<Note>
  **A janela de envio fecha sozinha.** Documentos só são aceitos enquanto o caso está em
  `under_review` e dentro do prazo em `deadlineAt`. Passado isso, o upload é recusado — e quem define
  esse prazo é a adquirente, não você.
</Note>

***

## Veja também

<CardGroup cols={2}>
  <Card title="Pagamentos" icon="credit-card" href="/pt-BR/payments">
    O pagamento contestado, e os status `in_protest` e `chargeback`.
  </Card>

  <Card title="Carteiras" icon="wallet" href="/pt-BR/wallets">
    Onde aparecem a reserva, o estorno da reserva e a multa.
  </Card>

  <Card title="Taxas" icon="percent" href="/pt-BR/valores/taxas">
    Como a taxa e a multa de chargeback são configuradas.
  </Card>

  <Card title="Simular eventos" icon="flask-conical" href="/pt-BR/sandbox/simular">
    Dispare um chargeback de teste para exercitar a consulta e o upload.
  </Card>
</CardGroup>