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

# Como responder a disputas

> Guia operacional para acompanhar uma disputa, preparar a documentação e enviar a contestação para análise dentro do prazo.

Uma **disputa** acontece quando o portador questiona uma cobrança de cartão.
Quando isso acontece, a Chargefy cria um objeto `dispute` ligado à `charge`
original e abre um prazo para envio de evidências.

Este guia mostra o que fazer quando uma disputa é criada, quais arquivos são
aceitos, como enviar a contestação e como acompanhar a decisão.

<Info>
  O prazo de defesa é de **7 dias corridos** a partir da emissão da notificação.
  Use o campo `evidence_details.due_by` do `dispute` como fonte de verdade para
  o prazo.
</Info>

## Resumo do fluxo

1. Receba o webhook `charge.dispute.created` ou veja a disputa no Dashboard.
2. Consulte o `dispute` e confirme `status`, `reason`, `charge` e
   `evidence_details.due_by`.
3. Reúna todos os documentos em **um único arquivo**.
4. Faça upload da evidência antes do prazo.
5. Envie a contestação para análise.
6. Acompanhe `charge.dispute.updated` e `charge.dispute.closed` até a decisão
   final.

| Acontecimento                       | Transição                              |
| ----------------------------------- | -------------------------------------- |
| A disputa é criada e exige resposta | Início<br />→ `needs_response`         |
| A contestação é enviada             | `needs_response`<br />→ `under_review` |
| Você concede a disputa              | `needs_response`<br />→ `lost`         |
| A defesa é aceita                   | `under_review`<br />→ `won`            |
| A defesa é recusada                 | `under_review`<br />→ `lost`           |

## O que muda quando a disputa nasce

Quando o `dispute` é criado, ele normalmente começa em `needs_response`.
Nesse estado, a organização ainda pode enviar evidências.

Campos importantes:

| Campo                               | Como usar                                                                           |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| `id`                                | ID da disputa (`dp_*`). Use em consultas, upload e envio para análise.              |
| `charge`                            | Charge contestada (`ch_*`). Use para reconciliar com pedido, invoice ou assinatura. |
| `amount`                            | Valor contestado, em centavos.                                                      |
| `customer`                          | Customer relacionado, quando disponível.                                            |
| `evidence_details.due_by`           | Prazo final para envio da contestação.                                              |
| `evidence_details.has_evidence`     | Indica se já existe arquivo associado.                                              |
| `evidence_details.submission_count` | Quantidade de envios para análise já feitos.                                        |
| `reason`                            | Motivo normalizado quando disponível. Pode ser `null`.                              |
| `status`                            | Estado atual da disputa.                                                            |

Os valores possíveis de `status`:

| Valor                    | Descrição                                                    |
| ------------------------ | ------------------------------------------------------------ |
| `warning_needs_response` | Alerta prévio de disputa aguardando resposta da organização. |
| `warning_under_review`   | Alerta prévio com resposta enviada, em análise.              |
| `warning_closed`         | Alerta prévio encerrado sem virar disputa.                   |
| `needs_response`         | Disputa aberta aguardando o envio da contestação.            |
| `under_review`           | Contestação enviada, em análise.                             |
| `won`                    | Decisão final favorável à organização.                       |
| `lost`                   | Decisão final favorável ao portador.                         |

Os valores possíveis de `reason`, quando informado:

| Valor                   | Descrição                                                       |
| ----------------------- | --------------------------------------------------------------- |
| `fraudulent`            | O portador alega fraude na cobrança.                            |
| `product_not_received`  | O comprador alega não ter recebido o produto ou serviço.        |
| `product_unacceptable`  | O produto ou serviço recebido estava em desacordo com a oferta. |
| `duplicate`             | O comprador alega cobrança em duplicidade.                      |
| `credit_not_processed`  | Um reembolso prometido não foi processado.                      |
| `subscription_canceled` | Cobrança feita após o cancelamento de uma assinatura.           |
| `unrecognized`          | O portador não reconhece a cobrança.                            |
| `general`               | Motivo genérico, sem categoria específica.                      |

<Note>
  No 8º dia corrido, pode haver ajuste financeiro relacionado à contestação.
  Isso não significa decisão final. O `dispute` público permanece em
  `under_review` enquanto a análise final estiver em andamento.
</Note>

## Prazos e estados

| Momento             | O que acontece                                          | O que você deve fazer                                    |
| ------------------- | ------------------------------------------------------- | -------------------------------------------------------- |
| Dia 0               | Disputa criada em `needs_response`.                     | Comece a reunir documentos imediatamente.                |
| Até 7 dias corridos | A contestação ainda pode ser enviada.                   | Faça upload do arquivo e envie para análise.             |
| Dia 8 em diante     | A disputa segue em análise quando a defesa foi enviada. | Acompanhe webhooks e reconciliação financeira.           |
| Decisão final       | O `status` muda para `won` ou `lost`.                   | Trate `charge.dispute.closed` e atualize seu backoffice. |

A decisão final pode levar semanas e, em alguns casos, até cerca de 120 dias.
Evite fazer polling agressivo: use webhooks para acompanhar a mudança de
estado.

## Requisitos do arquivo

A defesa deve ser consolidada em **um único arquivo**. A Chargefy não aceita
múltiplos anexos para a mesma submissão.

| Requisito              | Valor                            |
| ---------------------- | -------------------------------- |
| Formato                | PDF ou TIF                       |
| Tamanho máximo         | 7 MB                             |
| Quantidade de arquivos | 1 arquivo                        |
| PDF                    | Até 10 páginas                   |
| Resolução              | Até 200 DPI                      |
| Orientação             | Páginas verticais                |
| Cor                    | Preferencialmente preto e branco |

Também recomendamos:

* Não envie arquivo protegido por senha.
* Não envie páginas em branco.
* Use nomes de arquivo simples, sem caracteres especiais.
* Garanta que textos, comprovantes e datas estejam legíveis.
* Consolide prints, comprovantes, conversas e recibos no mesmo PDF/TIF.

<Warning>
  Se o arquivo estiver ilegível, exceder o limite ou for enviado fora do prazo,
  a contestação pode não ser analisada. O upload valida formato, tamanho e
  contagem de páginas do PDF; qualidade visual e conteúdo continuam sendo
  responsabilidade da organização.
</Warning>

## O que incluir na defesa

Monte o documento pensando em uma pessoa que não conhece a venda. O arquivo
precisa explicar por que a cobrança é legítima ou por que o produto/serviço foi
entregue corretamente.

### Fraude ou cobrança não reconhecida

Inclua evidências que conectem o comprador à transação:

* Recibo ou comprovante de compra.
* Dados de autenticação, login, IP, dispositivo ou aceite de termos, quando
  existirem.
* Comprovante de entrega, uso, acesso ou ativação do serviço.
* Comunicação com o comprador reconhecendo a compra.
* Em casos de fraude, inclua o vínculo com **Mensagem Emissor** quando
  aplicável.

### Produto não recebido

Inclua evidências de entrega ou disponibilização:

* Código de rastreio, comprovante de postagem ou comprovante de entrega.
* Data e endereço de entrega.
* Logs de acesso, ativação ou download em produtos digitais.
* Histórico de atendimento mostrando resolução ou tentativa de contato.

### Produto inaceitável, cancelamento ou desacordo comercial

Inclua contexto comercial:

* Descrição do produto/serviço vendido.
* Política de cancelamento, troca ou reembolso aceita pelo comprador.
* Comprovante de aceite dos termos.
* Conversas de suporte.
* Evidências de que o serviço foi prestado ou que o produto estava de acordo
  com a oferta.

### Duplicidade, crédito não processado ou assinatura cancelada

Inclua linha do tempo e conciliação:

* IDs das cobranças relacionadas.
* Comprovantes de refund, cancelamento ou ausência de refund.
* Histórico de invoices, assinaturas ou pedidos.
* Datas de cobrança, cancelamento e comunicação com o cliente.

## Enviar pelo Dashboard

Use este caminho quando a operação é feita por uma pessoa da organização.

1. Acesse o Dashboard da Chargefy.
2. Entre em **Financeiro → Disputas**.
3. Abra a disputa.
4. Confira o prazo, valor, charge e customer.
5. Faça upload do arquivo PDF/TIF.
6. Revise o checklist exibido na tela.
7. Clique em **Enviar à análise**.
8. Acompanhe o histórico de envios na própria disputa.

Se a organização decidir não defender a cobrança, use **Encerrar**. Essa ação
concede a contestação e muda o `dispute` para `lost`.

## Enviar pela API

Use este caminho quando seu sistema opera disputas server-to-server. Para
plataformas, inclua o header `Organization` com a organização conectada que
originou a disputa.

### 1. Consulte a disputa

```bash theme={"theme":"css-variables"}
curl -X GET "https://api.chargefy.io/v1/disputes/dp_A3bcTcGXjaqcz1VW" \
  -H "Authorization: Bearer {{API_KEY}}"
```

Resposta resumida:

```json theme={"theme":"css-variables"}
{
  "id": "dp_A3bcTcGXjaqcz1VW",
  "object": "dispute",
  "amount": 15000,
  "charge": "ch_8jkm3zq9icME7BL8",
  "closed_at": null,
  "created_at": "2026-05-22T03:00:00Z",
  "currency": "brl",
  "customer": "cus_rPDKcQYE3M1J9uKC",
  "evidence": {},
  "evidence_details": {
    "due_by": "2026-05-29T03:00:00Z",
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "is_charge_refundable": false,
  "livemode": false,
  "metadata": {},
  "payment_intent": "pi_mALqiee6SkiBG3g9",
  "reason": "fraudulent",
  "status": "needs_response",
  "updated_at": "2026-05-22T03:00:00Z"
}
```

Veja o contrato completo em [Consultar dispute](/api-reference/disputes/get).

### 2. Faça upload do arquivo

Envie exatamente um arquivo no campo `file`.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/dispute-evidence-upload" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -F "dispute_id=dp_A3bcTcGXjaqcz1VW" \
  -F "file=@/caminho/local/defesa.pdf;type=application/pdf"
```

Para API key de plataforma:

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/dispute-evidence-upload" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_KgmNfKrEHmy8AePB" \
  -F "dispute_id=dp_A3bcTcGXjaqcz1VW" \
  -F "file=@/caminho/local/defesa.pdf;type=application/pdf"
```

Erros comuns de upload:

| Status | Quando ocorre                                                                                                          |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `400`  | Arquivo ausente, mais de um arquivo, MIME inválido, PDF sem contagem de páginas legível ou PDF com mais de 10 páginas. |
| `400`  | Arquivo acima de 7 MB.                                                                                                 |
| `404`  | Disputa não encontrada na organização autenticada.                                                                     |
| `409`  | Disputa já fechada.                                                                                                    |

### 3. Envie para análise

Depois do upload, envie `submit: true` no dispute.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/disputes/dp_A3bcTcGXjaqcz1VW" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "submit": true
  }'
```

Você também pode atualizar `metadata` e evidências textuais antes do envio:

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.chargefy.io/v1/disputes/dp_A3bcTcGXjaqcz1VW" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "customer_communication": "Conversation and receipt attached."
    },
    "metadata": {},
    "submit": true
  }'
```

Se o envio for aceito, o `dispute` passa para `under_review`.

<Warning>
  `POST /v1/disputes/{id}/close` não envia defesa. Essa ação concede a
  contestação e retorna o `dispute` como `lost`.
</Warning>

## Webhooks que você deve tratar

Configure seu endpoint para receber estes eventos:

| Evento                                                                     | Quando tratar                                                          |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`charge.dispute.created`](/api-reference/webhooks/charge.dispute.created) | Abrir tarefa operacional e iniciar coleta de evidências.               |
| [`charge.dispute.updated`](/api-reference/webhooks/charge.dispute.updated) | Atualizar status interno, evidência enviada ou contagem de submissões. |
| [`charge.dispute.closed`](/api-reference/webhooks/charge.dispute.closed)   | Registrar decisão final como `won` ou `lost`.                          |

Em plataformas, use o campo top-level `organization` do webhook para identificar
a organização conectada que originou a disputa.

## Checklist operacional

Antes de clicar em **Enviar à análise** ou enviar `submit: true`, confirme:

* O prazo `evidence_details.due_by` ainda não expirou.
* O arquivo é PDF ou TIF.
* O arquivo tem no máximo 7 MB.
* O PDF tem até 10 páginas.
* O documento está legível, vertical e preferencialmente em preto e branco.
* Todas as evidências estão consolidadas em um único arquivo.
* A defesa explica o contexto da compra, entrega, uso ou cancelamento.
* Seu sistema está preparado para receber `charge.dispute.closed`.

## Erros comuns

| Situação                  | Como evitar                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Perder o prazo            | Crie automação interna no recebimento de `charge.dispute.created` e trate `due_by` como prazo fatal.                |
| Enviar vários arquivos    | Consolide tudo em um único PDF/TIF antes do upload.                                                                 |
| Arquivo ilegível          | Revise o PDF/TIF como se fosse uma impressão: texto pequeno, cortes e páginas tortas reduzem a chance de análise.   |
| Enviar defesa sem arquivo | Primeiro faça upload, depois envie `submit: true`.                                                                  |
| Conceder por engano       | Use `close` somente quando a organização decidiu aceitar a perda da contestação.                                    |
| Ignorar `closed`          | A decisão final pode chegar muito depois do envio; trate `charge.dispute.closed` para fechar o caso no seu sistema. |